Docs

Troubleshooting

Recover from failed builds, blank previews, SQL and RLS errors, edge function 404s and missing secrets, and broken imports.

Chapter 01

Recovery flow

Wait for the work session to finish.
Open Issues if a build failed.
Try Rebuild when preview is stale.
Use Fix all after auto-fix is exhausted.
Roll back to the last known-good version if needed.

Chapter 02

Blank or stale preview

A blank preview is usually one of three things, in this order of likelihood.

The build failed: Check Issues. A failed build leaves the last working preview in place or nothing at all, depending on how far it got.
The build succeeded but the app throws on load: The page is blank rather than broken-looking because a top-level error stops React mounting anything. Ask NeoBuild to check the console error, or prompt the fix directly.
The preview is stale: Rebuild re-runs the current version. Do this before assuming the code is wrong.

Missing database credentials look like a blank page

If the app expects Supabase and has not been given its environment values, it can fail at startup. Linking a database triggers a rebuild so the app receives its credentials — if you linked one and did not rebuild, do that first.

Chapter 03

Database and RLS errors

Most database errors after a successful build are permission errors rather than schema errors — the table exists, but row-level security is refusing the request.

42501, or "permission denied for table": An RLS policy or grant is missing. NeoBuild can run an idempotent RLS and GRANT repair before preview when enabled; if that repair fails, you still need Review SQL → Apply.
Rows return empty for a signed-in user: The query succeeded and the policy filtered everything out. Check that the policy matches on the column you actually store the owner in.
"relation already exists" when applying SQL: The script is not idempotent. Ask for it to be rewritten with create table if not exists and safe alter statements, then apply again.

Example prompt

Repair the pending SQL: Supabase says relation tasks already exists. Make it idempotent using create table if not exists and safe alter statements.

Nothing is applied without you

A failed script has not half-run. SQL is applied only when you approve it, so a rejected script leaves the database as it was.

Chapter 04

Edge function errors

404 from the function URL: The function was never published to Supabase. Check Build History for an edge publish on this version, then run Publish server features and try again.
500 mentioning a missing environment variable: The secret exists in the code but not on the server. Add it in Environment Variables and republish — adding it to client env vars will not work, because the function reads its own runtime environment, not the frontend bundle.
401 or 403 from a third-party API: The secret is set but wrong, or belongs to the other environment (a test key against a live endpoint). Confirm the value, then republish.
Function works in preview but not after publish: The published app is pointing at a version whose functions were never deployed. Republish server features from the version you actually published.
Security advisory about a secret: A key is being used somewhere it would reach the browser. Move that call into an edge function and read the secret there instead.

Check Build History first

Most edge function problems are deploy problems, not code problems. Build History tells you whether the function was ever published for the version you are running.