Use this guide when BaseBuddy shows an error, a request fails, or a production deployment behaves differently than expected.

BaseBuddy does not have an in-app log viewer. Server logs come from the host that runs BaseBuddy, such as your deployment platform, container runtime, process manager, or terminal session. If you start BaseBuddy with pnpm start, it runs the production Next.js server on port 8080, which is the same as next start --port 8080.

The goal is to match the user-visible failure to the right server log entry, then fix the first failing layer instead of changing setup, mapping, or permissions blindly.

Start with the visible failure

Before opening logs, write down what happened in the browser.

Then open the logs for the host running BaseBuddy and search near that time.

Check the place that owns the running process:

• the terminal where pnpm start is running;
• your deployment provider logs;
• your container logs;
• your process-manager logs.

Stay close to the timestamp of the failed action. A later error can be a result of the first failure, not the cause.

Use setup checks before deeper log reading

If the app redirects to onboarding, setup checks fail, or projects cannot load after an env, deployment, database, Auth, or storage change, start with setup diagnostics.

Open:

texthttp://localhost:8080/onboarding?diagnostics=1

If the browser cannot render BaseBuddy, run the CLI check from the BaseBuddy repo:

shpnpm setup:check

Use the first failed setup section as your starting point. For deployment-specific setup checks, use How to run setup checks after a deployment or upgrade. If setup checks are failing, use How to fix failed setup checks before changing mapping or content.

Identify the failing layer

Most failures fall into one of these layers. Use the browser symptom and the nearby server log together.

BaseBuddy should keep unsafe mappings read-only or unsupported instead of guessing. If an edit button is missing or a screen is read-only, use How to troubleshoot missing edit buttons or read-only screens.

Read common log clues

BaseBuddy logs should help you find the failing route or layer without exposing secrets.

Content request failures often include a route prefix like:

text[content-runtime-route][...]

Use the endpoint name, timestamp, and projectId to match the log to the browser action. Do not paste private content or full request bodies into an issue just because the route failed.

Slow content reads can appear as:

text[content-runtime][slow-request]

These logs include timing information such as endpoint, duration, budget, cache state, status, and spans. A slow-request log does not always mean the request failed. It means the request took longer than the route budget and should be checked for database, mapping, relation, count, or storage performance.

Cache warmup or rebuild work can appear as:

text[content-runtime][cache-build]

Use these entries when a page loads slowly after a restart, deployment, or mapping change.

Invitation and member-management errors may include route-specific prefixes for member invitations. Match those logs to the invite, accept, revoke, or members action the user took.

Match status codes to likely causes

Status codes are not the whole answer, but they point you toward the right layer.

If image or file URLs are broken after upload, move, delete, or storage changes, use How to fix broken image or file URLs.

Keep secrets out of logs and support messages

Do not share:

• full .env files;
• database URLs;
• service-role keys or secret keys;
• cookies or session values;
• certificates;
• signed URLs or long signed URL query strings;
• private emails;
• private content screenshots;
• full request bodies.

Redact before sharing. If you need to show that a value is set, share the env variable name and a short note like set, missing, or redacted, not the value itself.

pnpm setup:check and browser diagnostics are designed to redact sensitive values, but you should still review copied output and screenshots before posting them anywhere public.

Collect a safe support bundle

When you need help, collect the smallest bundle that explains the failure.

• BaseBuddy release, tag, or commit.
• Which app-data backend is selected, and whether it exists and validates.
• The page or route where the issue happened.
• The action you took.
• The timestamp of the failure.
• The user-visible error and HTTP status, if visible.
• Redacted /onboarding?diagnostics=1 or pnpm setup:check output when setup may be involved.
• A short server log excerpt from the same timestamp, with secrets removed.
• The exact steps to reproduce the issue.

Do not include private content or a full request payload. If the issue involves one field, describe the field type and mapping shape instead of pasting the real content value.

Verify after the fix

After you fix the first failing layer, test one narrow action again.

For setup changes, rerun setup diagnostics. For content or mapping changes, open one safe item and test one harmless edit. For workflow issues, test Publish, Unpublish, or Archive separately from normal Save.

BaseBuddy reads the saved mapping as the runtime truth. Normal Save writes dirty fields only, and Publish, Unpublish, and Archive stay explicit actions. Do not use log debugging as a reason to reshape user tables, broaden permissions, or make unsupported fields writable.

For production operating checks, see Operations and Production readiness.

Related pages

• Deployment
• Operations
• Production readiness
• How to run setup checks after deployment or upgrade