Troubleshooting

Installation issues

If install commands fail, confirm the required Node.js version, package manager, lockfile, and dependency installation path. Re-run the install after clearing only generated artifacts that are safe to remove.

Environment variable issues

Missing or misspelled variables are a common source of setup failures. Compare your local file with the documented placeholders and restart the development server after changes.

Authentication issues

Authentication failures often come from mismatched callback URLs, missing AUTH_SESSION_SECRET or TOKEN_ENCRYPTION_KEY values, missing Supabase public auth variables, or provider credentials that do not match the local NEXT_PUBLIC_APP_URL.

Database connection issues

Check DATABASE_URL, database availability, required migrations, and network access. Confirm the configured user can read and write the expected database objects.

GitHub integration issues

Verify GITHUB_TOKEN, GITHUB_OWNER, GITHUB_REPO, repository permissions, and callback URLs. If access was recently changed, reconnect the repository before testing again.

Missing product context

If roadmap or documentation workflows seem incomplete, review whether Product Truth contains the objective, feature, decision, or repository context needed for the workflow.

Documentation generation issues

Generated drafts can be incomplete when source context is missing or stale. Update Product Truth and roadmap links, then regenerate and review the draft before sharing.

How to report a bug

Use the format below and remove secrets from logs, environment variables, URLs, screenshots, and copied terminal output before reporting an issue.

Problem
[What you see]

Likely cause
[Most common cause]

Fix
[Step-by-step fix]

Still stuck?
Open an issue with:
- Environment
- Steps to reproduce
- Expected behavior
- Actual behavior
- Logs, with secrets removed