Use this guide when you want to open a public BaseBuddy bug report and need to include enough detail for someone else to reproduce it.

A good public report explains the exact BaseBuddy version, deployment shape, page, action, expected result, actual result, and a small safe log excerpt. It should not include secrets, private content, full request bodies, cookies, signed URL query strings, or vulnerability details.

If the report involves a possible vulnerability, exposed credential, authorization bypass, data leak, or exploit path, do not open a public GitHub issue. Use the private process in Security instead.

Decide whether this is a bug report or a security report

Open a public issue for reproducible product bugs, setup failures, mapping behavior, editor errors, upload problems, sign-in return problems, or deployment issues that do not expose a weakness.

Use the security process for anything that could help someone attack an install:

When in doubt, start private. A maintainer can move a safe product bug into public later.

Collect version and install context

Use the issue fields from `SUPPORT.md` as your starting point.

textBaseBuddy version or commit:
Deployment target:
Node version:
pnpm version:
App-data backend: basebuddy-data / supabase-same-project / supabase-split-project
Supabase/Postgres version if known:
Output from pnpm setup:check with secrets redacted:
What you expected:
What happened:
Steps to reproduce:
Relevant server log excerpt with secrets removed:

For the BaseBuddy version, include the release, tag, or commit you deployed from the public repository. For deployment target, name the host or runtime shape, such as local pnpm start, Docker, VPS, Dokploy, Render, Fly.io, Railway, or another platform.

For deployment context, say where BaseBuddy is hosted and which app-data backend it uses. Do not paste your env values. Install credentials come from environment variables only. App data stores BaseBuddy mapping and app state, not database passwords, service-role keys, S3 secrets, or per-project credentials.

Write reproduction steps someone else can follow

Keep the reproduction short and exact. Include the visible page, action, time, and result.

If the issue involves content editing, say whether the action was normal Save or an explicit workflow action such as Publish, Unpublish, or Archive. BaseBuddy treats those as different paths: Save writes dirty mapped fields only, while workflow actions intentionally write the mapped workflow state.

If the issue involves mapping, describe the saved mapping shape instead of pasting private content:

textMapped field: summary
Storage target: posts.summary
Value kind: text
Cardinality: single
Editable: expected writable
Action: changed only this field and clicked Save

BaseBuddy reads the saved mapping as the runtime truth. A bug report should explain what the mapping says and what the runtime did with it. Do not include private table data, full rows, full request bodies, or screenshots of private content.

Include setup context only when it matters

If the bug started after installation, deployment, upgrade, env changes, database password rotation, Auth changes, app-data backend changes, or storage credential changes, include setup diagnostics.

Open browser diagnostics when BaseBuddy can render:

texthttps://your-basebuddy-domain.example/onboarding?diagnostics=1

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

shpnpm setup:check

The browser diagnostics and pnpm setup:check output are designed to redact sensitive values, but you still need to review anything you copy into a public issue. Remove database URLs, project refs, private domains, private emails, internal hostnames, and any value that looks like a key, token, password, certificate, or signed URL.

For setup-specific help, use How to run setup checks after a deployment or upgrade and How to fix failed setup checks.

Add safe log clues

BaseBuddy does not have an in-app log viewer. Logs come from the host that runs the BaseBuddy process: your terminal, deployment provider, container runtime, or process manager.

When you include logs, keep only a small excerpt from the same timestamp as the failed action. Remove secrets and private content before posting.

Useful public clues include prefixes like:

text[content-runtime-route]
[content-runtime][slow-request]
[content-runtime][cache-build]

Those prefixes can help maintainers identify the failing route, slow content read, or cache build without needing private content. Include the route name, timestamp, HTTP status, duration, and safe error text if present.

Do not include:

• full request bodies;
• full response bodies that contain private content;
• full .env files;
• database URLs;
• Supabase service-role keys or secret keys;
• S3 access keys or secret keys;
• session cookies;
• certificates;
• access tokens;
• private emails;
• signed URL query strings;
• screenshots of private content.

If a signed URL appears in a log, remove the query string or replace the whole value with [signed URL redacted].

For more log-reading guidance, use How to read BaseBuddy logs when something fails.

Add safe screenshots

Screenshots are useful when they show the visible state that is hard to describe: a failed setup section, a disabled button, a read-only field, a specific editor error, or a browser network status.

Before posting a screenshot publicly:

1. Crop to the smallest useful area.
2. Hide private content, private emails, project refs, database hostnames, file names that reveal customer data, and private URLs.
3. Remove browser extensions, profile menus, and unrelated tabs.
4. Remove signed URL query strings from the address bar or network panel.
5. Check the image again after redaction.

If the screenshot is mainly private content, do not post it. Describe the visible state instead.

Review the report before you post

Use this final pass before opening a public issue in the BaseBuddy repository.

• The report is a product bug, not a security issue.
• The steps reproduce from a clean page load.
• The BaseBuddy release, tag, or commit is included.
• The deployment target, Node version, pnpm version, browser, and app-data setup status are included.
• The page or route, action, timestamp, expected result, actual result, error, and status code are included.
• Setup diagnostics are included only if setup, deployment, env, Auth, database, or storage changes may be involved.
• Log excerpts are short, timestamp-matched, and redacted.
• Screenshots are cropped and redacted.
• No secret, credential, cookie, certificate, token, database URL, S3 secret, full .env, private email, private content, signed URL query string, security detail, or full request body appears in the report.

If you accidentally shared a secret, edit the public issue to remove it, then rotate the exposed value. Removing the text is not enough once a credential has been public. Use How to rotate exposed Supabase keys and database passwords as the first recovery step.

For deeper background while preparing a report, see Troubleshooting, Operations, Caps and rate limits, Production readiness, and Contributing.

Related pages

• Troubleshooting
• How to fix failed setup checks
• How to read BaseBuddy logs when something fails