Troubleshooting

Start in your project directory:

npx --yes getstead@0.2.1 doctor
npx --yes getstead@0.2.1 runs

Diagnostics reports OK, ACTION, or NOTE. Follow ACTION instructions first. A note about an allowance does not necessarily mean you reached it. The console’s Diagnostics page presents the same checks.

Verification email did not arrive

Check the address you registered and the spam folder. Developer and customer registrations are separate; a developer verification email does not verify a customer account. Request another verification email from the corresponding sign-in flow and use the newest link.

For customer mail, verify that your callback origin is saved in the project’s browser origins. Expired or already-used links should be replaced through the app. If delivery still fails, report the approximate UTC time, whether it was developer or customer verification, and any request reference. Never forward the full link or token.

Login fails

Verify the email first, and use the password for the correct account type. Developer login is at app.getstead.dev; customer login is inside your application. Use password reset on the relevant sign-in screen if needed.

For terminal login, run getstead login --api-url https://api.getstead.dev. Check the matching browser code and authorize only a request you initiated. If the CLI says you are logged into another API URL, sign in to the intended URL again. A password reset revokes developer sessions, so reauthorize the terminal afterward.

If commands select an unexpected project, check stead.json.projectId. An inherited STEAD_PROJECT_SECRET makes project commands use that credential instead of your developer session. Remove a stale value from the command’s environment; do not print it.

Browser-origin or CORS errors

In project Settings, add the exact origin shown in your browser: scheme, hostname, and port, without a path. localhost and 127.0.0.1 differ. Production requires HTTPS; local loopback HTTP is allowed. Register the application’s origin, not just the console domain.

If the starter’s port is occupied, stop the other process or start Vite on another fixed port, for example npm run dev -- --port 5174, and register http://localhost:5174. Use that same origin in callback URLs. Refresh the app after saving.

Do not work around an origin failure by adding a project secret to the browser, disabling origin checks, or sharing cookies across every subdomain.

Provider key, model, or credit errors

Save a valid key and matching base URL in the project’s Settings. The starter uses https://api.openai.com/v1 and gpt-5.6-luna. Check the provider account’s credit and model access. Run getstead doctor --check-provider to make a small billable test of the saved key, then inspect its run.

The hosted service uses the saved project key. Changing your local OPENAI_API_KEY does not change it. For getstead keys set, a nonempty STEAD_PROVIDER_KEY overrides piped input; remove stale exported values before a rotation. The CLI does not automatically read .env.

An unknown model or missing price is a configuration error. Use a supported curated model. Do not remove budgets to disguise a model that the hosted workflow cannot configure.

Deployment fails

Read the first error and inspect stead.json. Ensure the built ESM file exists, exported handlers match tool names, and the bundle is under 512 KiB. Bundle dependencies yourself. Run from the project root or pass --config.

For SQL errors, add a new migration instead of editing applied history. Check grants, forced RLS, identity-helper references, and exposed columns. Temporary tables and database administration are unavailable to the restricted project role.

For an interrupted response, refresh Diagnostics before retrying the same files. Automatic recovery can finish publication after committed migrations; do not force replay by renaming them. A 5xx after a change does not prove nothing happened.

Capacity or storage limit

Use the diagnostic’s named resource to choose the remedy. For full deployment retention, finish or cancel older unfinished runs and retry. For run history, older terminal records become eligible for automatic reclamation after 24 hours. Reduce large step inputs/results if a single run reaches its event limit.

For SQL scratch exhaustion, reduce sort/join size or add an index. For a storage-limited database, deploy a reviewed migration to drop or truncate unused objects/data; ordinary row deletion may not return disk space. Customer writes resume when space is restored.

If the beta’s database allocation pool is full, existing projects remain available but a new project cannot provision immediately. Retry later. Do not create more projects as a workaround.

Project deletion stays pending

Deletion runs asynchronously. getstead projects list and the console show its progress. If the message says database storage deletion is pending, the infrastructure provider has not finished removing the volume. Stead retries automatically; while the provider reports pending destruction, those checks are spaced one hour apart. This interval is not a completion deadline.

Keep the existing deletion request. Creating a replacement project or repeatedly requesting deletion does not speed up storage removal. A deleting project is unavailable for new work and can remain listed until cleanup finishes.

Approval stays pending

Open the owner’s Approvals page, inspect the action and expiry, and approve or deny it there. The customer’s token cannot resolve an approval. A successful decision triggers automatic resume; follow the original run instead of starting another refund.

If the approval expired or was already resolved, refresh the queue and trace. A stale decision can return 404 without implying the run disappeared.

Run interrupted or chat appears stuck

Inspect the run’s status, stream connection, and recovery message separately. Closing a tab does not cancel server work. Use Cancel run or client.cancelRun to request cancellation, then wait for the terminal outcome. A cancellation cannot undo an already completed external action.

For a manual resume, use getstead run --resume "$RUN_ID". If the run is busy, let the current execution settle. A conversation allows one unfinished turn; resolve, finish, or cancel it before sending another.

If events arrive on the network but your Vite app does not update, include the getsteadClient() Vite plugin from @getstead/client/vite, restart Vite, and reload. The starter already uses it.

Report a reproducible issue

Send the person who invited you: the page/command, expected and actual result, steps to reproduce, package versions, browser/OS, approximate UTC time, project/run/approval ID if relevant, and any opaque request reference. getstead doctor --json can help, but inspect and redact it before sharing.

Do not include passwords, provider keys, project secrets, session cookies, bearer tokens, full verification/reset/CLI authorization links, or private customer inputs and tool results. A redacted error and request reference are more useful than a screenshot full of credentials.