For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/web/troubleshooting.md (or send Accept: text/markdown).
Troubleshooting
Diagnose setup problems at the boundary that actually failed.
Setup and configuration
Before any step, read Before you start and Terminal basics. These instructions assume you opened the full supastack monorepo in VS Code; its root package.json marks the repository root. In pnpm commands, a workspace package is an app or shared-code folder; in the product, a workspace is a team's data container and security boundary. corepack pnpm --filter ... selects one package from the monorepo while commands run from its root. If you opened only a synced mobile or desktop folder, it does not contain the Web backend, Docker setup, or root scripts: run the backend from this monorepo or a reachable hosted server, and use the platform folder's own scripts. An environment variable is a named setting stored in a local .env file or your hosting dashboard; restart the relevant app after changing it, and keep server secrets out of NEXT_PUBLIC_ and EXPO_PUBLIC_ values.
1. Copy the first useful error line and the command that produced it; do not paste secret values.
2. From the repository root run corepack pnpm --filter @supastack/web typecheck for Web type errors, or corepack pnpm test for the automated suite.
3. For a browser issue, start Web with corepack pnpm --filter @supastack/web dev and reproduce it at http://localhost:3000. Expected: you can tell whether the failure is in setup, code, database, provider, or the browser before changing settings.
Read the failing command and first relevant error before changing configuration. Determine whether the failure is dependency installation, compilation, environment validation, database access, provider dispatch, or browser behavior.
corepack pnpm --filter @supastack/web typecheck
corepack pnpm --filter @supastack/web build
corepack pnpm testCommands to copy
Follow the comments to see which folder a command runs in. If two terminals are labeled, open two terminal windows and keep the first command running while you use the second.
corepack pnpm --filter @supastack/web typecheck
corepack pnpm testFirst-run errors, decoded
The first run fails in a small set of ways. Match the first red error line to a row — later errors are usually consequences of the first, so fix the top one before anything else.
| Symptom | Likely cause | First fix |
|---|---|---|
| node, corepack or pnpm is not recognized / command not found | The tool is not installed, or the terminal was open before installation finished | Install it (or reopen the terminal), then retry node --version |
| No package.json found / ENOENT package.json | The terminal is in the wrong folder | cd into the repository root — the folder that contains package.json — and retry |
| EADDRINUSE / port 3000 is already in use | Another dev server still holds the port | Find that server's terminal and press Ctrl + C, then start again |
| ECONNREFUSED to localhost:5432 or a database connection error | Postgres is not running | Run docker compose up -d postgres, wait for healthy, then retry |
| Env validation error naming a missing key | apps/web/.env.local is missing or has an empty required value | Copy the named key from .env.example, give it a value, save and restart the server |
| corepack or pnpm missing after corepack enable | No pnpm shim is on PATH | Use corepack pnpm ... directly — it never needs a shim; on Windows use corepack.cmd |
| PowerShell says a .ps1 script cannot run / is blocked | PowerShell's script policy blocks the shim | Use the .cmd form — corepack.cmd pnpm install — no policy change needed |
Implementation workflow
For missing API access, verify the server is running and the configured origin matches the client. For unavailable AI choices, inspect AI_MODEL_POLICY and enabled catalogue rows. For an uncertain queued task, use the saved recovery flow instead of starting another submission.
For browser layout issues, inspect computed styles and reproduce the exact viewport. Product chrome tokens live in app-theme.css (packs from catalog.ts); marketing brand lock lives in theme.css. Component overrides can still win through specificity. Check the rendered radius rather than only the token declaration.
Verification and troubleshooting
If the page is on :3001, open :3000 for the Web app; :3001 belongs to the separate apps/docs server. If a test asks for database access, use an isolated development database and check both .env locations. If the same error remains, include the command and sanitized first error line when asking for help; never disable access checks or print secrets to logs.
Do not solve a failing check by disabling authorization, logging secrets, or treating skipped infrastructure checks as passed. Capture a small reproduction and the relevant non-secret configuration. Re-run the failing check after the fix, then the affected regression tests.