Troubleshooting Raytha: 404 pages, templates, images, login and email

Most Raytha problems have one of a few causes, and each leaves a clue: a badge, an error message, a log row. This page lists the common symptoms with the cause and the fix for each. Work through the steps in order and stop when the problem is gone.

A page shows 404 after I published it

Raytha answers 404 whenever the address does not lead to something that is published. Find the kind of thing you are looking at.

A content item (post, page, custom item)

Open the item under Content. Next to the title is a badge: Published or Unpublished. A Draft badge beside Published means the live version is older than your latest edit.
If it says Unpublished, click Publish. Save draft keeps the item hidden from visitors.
In the Settings card, check Route path. The public address is your site's address plus that path. A typo, or a path that differs from the link you are using, gives a 404.

The Preview button opens the item with ?previewDraft=true, which shows unpublished items only to signed-in people who may edit that content type. If Preview works and the plain address gives 404, the item is not published.

A list view

Open the content type, then the view, and choose the Public tab.
Tick Published, check Route path, and choose a Template.
Click Save public settings.

A view that is not published answers 404 even if every item in it is published.

A site page

Open the page under Content > Site pages and click Publish. Use Save settings to correct its route path. The page builder keeps changes as a draft until you publish.

The home page

If only / gives 404, the page chosen as the home page is not published. Publish it, or choose another. See Set a content item as the home page.

Still 404

Another item or view may use the same route path. Raytha refuses duplicates when saving, so look for a recent error message.
Some first segments are reserved for Raytha itself and are refused: raytha, account, api, healthz, _static-files, favicon.ico, and anything starting with raytha_.
A trailing slash in the address is ignored. Raytha compares paths without regard to upper or lower case when it checks for duplicates.

The template is "not allowed" for a content type

When you save an item, a view's public settings or a bulk template assignment, Raytha checks that the template may be used for that content type. These messages mean the check failed:

Message	Cause
This template does not have access to this model definition.	The template is not ticked for this content type. ("Model definition" is the older name for a content type.)
This template does not have access to this content type.	The same problem, raised by a bulk template assignment.
This template does not apply to the current active theme.	The template belongs to a theme that is not the active one.

Open Design > Themes and confirm which theme is active.
Open the template inside that theme.
Under Content types that can use this template, tick the content type. Tick Content types created later if the template should be available to future types.
Save the template, then save the item or view again.

The Template drop-down on an item or view only lists templates from the active theme that allow its content type. If the one you want is missing, the steps above add it. See Themes and web templates.

Images are not showing

Check the file exists. Open Content > Media, open the file, and look at its preview. If the preview is broken, the stored file is missing; see "Files disappear after a restart" below.
Check the snippet. Open the file and copy the snippet again. Public URL (attachment_public_url) gives the file's direct address and suits public storage. Redirect URL (attachment_redirect_url) is a Raytha link that redirects to the file and also works with private cloud storage. A wrong object key, or a key from a file you deleted, gives nothing.
Check the file type and size. Raytha refuses an upload with "File type is not allowed." unless the type is in the server's allowed list, which by default covers text, images, video, audio and PDF. With local storage, a file over the size limit (20 MB by default) is refused too. The person who runs the server changes these with FILE_STORAGE_ALLOWED_MIMETYPES and FILE_STORAGE_MAX_FILE_SIZE.
Check Website URL. In Settings > Configuration, Website URL is used to build full links. If it is wrong, images in emails and in API responses point at the wrong place.

Files disappear after a restart

With the default local storage, uploads live in a folder on the server. If Raytha runs in Docker and that folder is not on a volume, the files are lost when the container is recreated. The supplied docker-compose.yml keeps them in the raytha_user_uploads volume. If you changed the compose file, make sure the volume is still mounted.

Uploads fail with cloud storage

With S3 or Azure Blob, the browser uploads directly to the bucket, which needs a CORS rule that allows your site's address. If uploads stall or fail only on cloud storage, ask whoever runs the server to check the bucket's CORS settings. Images served from a custom domain also need the matching custom-domain setting. See File storage.

I cannot sign in

The admin sign-in page is at /raytha/login. Public visitors use your site's own login page. The message on screen tells you what happened.

Message	Meaning and fix
Invalid email or password.	The address is unknown or the password is wrong. Raytha gives the same answer for both. Use Forgot password? on the sign-in page, or have an administrator reset it under People > Admins.
Too many failed login attempts. Please try again later.	Lockout. By default 10 failures within 60 seconds blocks further tries for that email address. Wait one window and try again. An administrator can change the limits under Settings > Authentication.
Your account has been deactivated. / User has been deactivated.	The account is suspended. An administrator restores it under People > Admins or People > Users.
Authentication scheme disabled for administrators. / …for public users.	That sign-in method is off for your kind of account. Turn on Enabled for admins or Enabled for users under Settings > Authentication.
Authentication scheme is disabled.	The method is off entirely, for example password sign-in. Enable it, or use another method.
Code is consumed or expired.	A magic-link code works once and expires. Request a new one.
Token is consumed or expired.	A password-reset link also works once and expires. Request another.
Security token has expired. / Invalid security token. / Security token already consumed.	Single sign-on with JWT. The token is old, signed with the wrong secret, or (with high security on) reused. Generate a fresh token. See JWT sign-in.
Failed authentication. / Missing 'email' attribute…	Single sign-on with SAML. The certificate or issuer does not match, or the identity provider does not send an email. See SAML sign-in.

No code or reset email arrives

Magic-link and password-reset both depend on outgoing email. Raytha says "If that address can sign in here, we emailed it a sign-in code" whether or not the address exists, so the screen alone does not prove anything was sent. Check Observability > Email log and the next section.

Locked out of the admin

If every administrator is locked out or the only sign-in method is broken, you need someone with access to the server. Prevent it by keeping one signed-in admin session open while you change Settings > Authentication, and by keeping password sign-in enabled for administrators as a fallback. See Enable different authentications and single sign-on.

Signed in, but sections are missing

The sidebar shows only what your roles allow. If Settings or Automation is missing, you lack Manage System Settings; if Audit log is missing, you lack Manage Audit Logs. Ask an administrator with Manage Administrators to adjust your role. See Manage administrators, roles and permissions.

Emails are not sending

Look at the email log. Open Observability > Email log. A Failed row shows the error from the mail server when you expand it. A message from the SMTP server about authentication means the user name or password is wrong. A timeout or "connection refused" points to the wrong host or port, or a blocked connection.
No row at all means Raytha never tried: the action that sends mail did not happen, for example a welcome email was not ticked.
A Sent row but no email: check the spam folder and your mail provider's own logs. If neither the server nor Settings > Configuration has an SMTP host, Raytha skips sending silently and the log can still say Sent.
Check Host, Port and Password under Override system SMTP. Retype the password after every save; a blank password field replaces the stored one with an empty one.
Check the From address. Many providers reject a sender they do not host. The server's SMTP_FROM_ADDRESS, if set, overrides Default from address.

The Send test button in this release does not work, so test with a real action. The steps are in Set up SMTP and email.

Where to look for more

Settings > Background tasks shows imports, exports, webhook deliveries and content-trigger Functions, with errors.
Observability > Audit log shows who changed a setting recently. See View the audit logs.
If a page renders but looks wrong, the problem is usually in the template. See How Liquid templates work in Raytha.

Gotchas

Change one thing at a time. Re-test after each change so you know which one fixed it.
Test in a private window. Your signed-in session can show drafts and admin-only content that visitors never see.
Read the message, not just the status. Raytha's errors name the cause. Copy the full text when you ask for help.