Troubleshooting

Use this page when something in Dyrected is not behaving the way you expected and you need the fastest way to narrow it down. By the end, you should know how to tell which layer is failing, what the common first checks are, and which deeper page to open next when you need feature-specific detail.

Start by classifying the failure

Most Dyrected problems fall into one of these buckets:

Recommended troubleshooting order

Use this order before you chase feature-specific details:

1. Confirm the app boots and the admin route loads.
2. Confirm you are using the right backend mode: Dyrected Cloud or self-hosted.
3. Confirm the required environment variables for that mode are actually present.
4. Confirm your schema changes were applied or synced.
5. Only then debug the feature itself: auth, preview, uploads, or email.

That order matters because later failures often come from an earlier layer. A broken preview flow is often a preview configuration problem, but it can also be a route-mounting problem or a missing Cloud sync.

Check the backend mode first

Dyrected has two setup shapes, and the first checks are different for each one.

Dyrected Cloud

Cloud projects depend on your app knowing how to talk to the Cloud site and, when you sync schema, how to identify that site.

The core values to check are:

DYRECTED_URL=
DYRECTED_API_KEY=
DYRECTED_SITE_ID=

Your frontend framework may also use public variants:

• Next.js: NEXT_PUBLIC_DYRECTED_URL, NEXT_PUBLIC_DYRECTED_API_KEY, NEXT_PUBLIC_DYRECTED_SITE_ID
• Nuxt: NUXT_PUBLIC_DYRECTED_URL, NUXT_PUBLIC_DYRECTED_API_KEY, NUXT_PUBLIC_DYRECTED_SITE_ID
• Vite React/Vue: VITE_DYRECTED_URL, VITE_DYRECTED_API_KEY, VITE_DYRECTED_SITE_ID

If npx dyrected sync:schema appears to do nothing, check DYRECTED_API_KEY and DYRECTED_SITE_ID first. The current CLI warns and skips sync when those are missing; it does not hard-crash by default.

Self-hosted

Self-hosted projects need the backend runtime pieces in place:

DATABASE_URL=
DYRECTED_JWT_SECRET=
ENCRYPTION_KEY=

If the app boots but auth, preview tokens, or persistence behave strangely, start by re-checking these before you change feature code.

For the full install paths, use Installation.

Admin route does not load

If /admin or your chosen admin path does not render, treat that as an integration problem before anything else.

The first checks are:

• Next.js must use the App Router path the install flow expects.
• React and Vue projects need the embedded admin route mounted manually in your app.
• If you moved the admin, confirm you changed the actual framework route, not just a Dyrected setting.

This is the main mental model: the admin location is owned by your framework route setup. Dyrected does not have a separate "move the admin" config switch that remaps it for you.

Use these pages for the exact route shape:

• Installation
• Admin Overview
• Custom Admin Panel Location

Schema changes are not showing up

If you changed dyrected.config.ts and the admin still looks old, figure out whether the problem is local runtime reload or Cloud sync.

Local or self-hosted projects

Start simple:

• restart the dev server after config-level changes
• confirm the collection or field is really exported in the active config
• confirm you are looking at the correct environment and database

Dyrected Cloud projects

If the frontend is connected to Cloud, but the admin schema does not reflect your latest config:

• rerun npx dyrected sync:schema
• confirm DYRECTED_API_KEY and DYRECTED_SITE_ID
• confirm the URL values point at the intended site
• read the sync output for warnings, not just errors

One important Cloud-specific check: some config has to stay serializable. The current sync command strips unsupported function-based access rules and warns about it. For preview URLs and other admin-facing config that needs to survive Cloud sync, prefer the Cloud-safe forms documented in the feature pages, especially Jexl strings where recommended.

If the shape is Cloud-specific, go deeper here:

• Admin Preview
• Authentication Overview

Auth is not working

Treat auth failures as one of three separate problems:

1. the auth collection was never set up correctly
2. the JWT secret is missing or inconsistent
3. the request is unauthenticated, even though the UI looks signed in

Common clues:

• "Database not configured" means the runtime does not have a working database adapter.
• "Invalid email or password." usually means the credentials are wrong, not that the route is missing.
• "Authentication required." means the endpoint ran, but no valid user session was present.

If first-user setup fails, remember that the bootstrap route only works before any user exists. Once the collection already has a user, the first-user path is closed by design.

Start with:

• confirm the collection has auth: true
• confirm DYRECTED_JWT_SECRET is set everywhere that handles auth
• confirm your client is actually sending the token or cookie on later requests

Use these pages for the feature-level path:

• Authentication Overview
• Authentication Operations
• JWT Strategy
• Cookie Strategy

Preview is not working

Preview issues usually come from confusing three different pieces:

• the document needs a URL
• the admin needs to know that URL
• the frontend needs to know how to render preview data

Start with admin.previewUrl. If that does not resolve for the current document, neither the "View" link nor the preview pane can help you.

Then check the preview mode:

• postMessage is the default and simplest path
• token is the server-side path for frontends that cannot receive browser messages directly

If you use Cloud sync, prefer the serializable previewUrl form documented on the preview page. A JavaScript function may work locally and then break once the schema is synced to Cloud.

If token preview fails, also check your JWT secret. The preview-token endpoint signs a short-lived token, and the preview-data endpoint rejects missing, invalid, or expired tokens.

Use these pages in order:

• Preview
• Live Preview Overview
• Frontend
• Server-side

Uploads or media are not working

Uploads in Dyrected depend on two separate decisions:

• a root-level storage adapter that knows where files live
• a collection with upload enabled that defines what can be uploaded

That means the first checks are:

• is storage configured at all
• is the target collection actually an upload collection
• does the file match the collection's MIME and size rules

Current runtime clues are fairly direct:

• "Storage not configured" means Dyrected has no storage adapter to write to
• "No file uploaded" means the request body did not include the file payload
• "Database not configured" means the file may have been processed, but Dyrected cannot persist the media document

If files upload but do not render, check the serving side too. Local storage and provider-backed storage have different rendering and URL concerns.

One useful edge case: "add media from URL" is a different path from binary file upload. In that flow, the admin creates an external media record from the URL you entered, so troubleshoot the external URL and media record creation separately from storage uploads.

Use these pages for the deeper path:

• Upload Overview
• Storage Adapters

Auth emails are not sending

If password reset, invite, welcome, or password-changed flows complete but no email arrives, check whether you are relying on development fallback or expecting production delivery.

The important split is:

• in development, Dyrected can fall back to Ethereal through nodemailer
• in production, you should treat a real email provider as required for any auth flow that depends on mail

That means the first checks are:

• confirm you configured the top-level email transport
• confirm the provider credentials you added are valid
• if you are in development with no provider, check the server logs for the Ethereal preview URL
• if nodemailer is not installed in that development setup, Dyrected logs a warning and skips sending
• if you are testing the self-hosted admin, check the dashboard's Needs attention panel for the "Email delivery is not configured" warning

Two behavior details matter here:

• the auth endpoint can still return success even if the send fails, because these built-in auth emails are best-effort

Also keep the flow semantics straight: a password reset sends two different auth emails over the whole flow. forgot-password sends the reset message, and a successful reset-password sends the password-changed notification.

Use Email Overview for the transport setup and built-in email behavior.

Request bodies are missing from logs

If you can see Dyrected request logs but the body field is missing, start by checking whether body capture was ever eligible for that request.

Dyrected only captures request bodies when all of these are true:

• observability.requestLogging.logBodies is true
• the request was sampled for body capture
• the request content-type includes application/json

That means these cases are expected:

• multipart uploads do not log raw file payloads
• binary payloads do not log raw body content
• JSON bodies larger than maxBodyBytes may be truncated and fall back to metadata-only logging if the truncated payload can no longer be parsed safely
• successful requests may log without a body when bodySuccessRate does not sample them

The fastest checks are:

• confirm observability.requestLogging.logBodies is enabled
• confirm the request really used application/json
• temporarily raise sampling.bodySuccessRate to 1 while debugging
• check whether the log event contains bodyCapture metadata instead of body

If the log entry includes bodyCapture with parseFailed: true or truncated: true, Dyrected did attempt capture but intentionally avoided logging parsed content.

For the config surface and defaults, use Logging and Observability.

When to stop here

This page is the first-stop guide, not the full reference for every feature. If you have already identified the failing layer, switch to the deeper feature page instead of staying in generic troubleshooting mode.

That is the recommended path:

• use this page to classify the problem
• use the linked feature page to finish the fix
• return here only when you are still unsure which layer is failing