Troubleshooting
Resolve the most common Ops setup, authentication, migration, and runtime configuration problems.
Most Ops startup issues come from one of four causes: missing Supabase configuration, broken connectivity, a repository that is not linked correctly, or a runtime payload that was never prepared.
This page focuses on those recurring problems so beginners can recover quickly and technical users know where to look next.
Missing Supabase configuration
- In a source checkout, make sure .env.local contains VITE_SUPABASE_URL and VITE_SUPABASE_PUBLISHABLE_DEFAULT_KEY.
- In an installed app, rerun the configuration workflow or provide the connection through the runtime form when the app asks for it.
npx polter app configure ops --path .Auth and network issues
- Check firewall, VPN, proxy, and DNS behavior first.
- Confirm the Supabase project URL and publishable key are correct for the environment you intended to use.
- Restart the app after changing connection details so it reloads runtime configuration cleanly.
Migration and link issues
npx polter app link ops --path .
npx polter app migrate ops lint --path .
npx polter app migrate ops push --path .If push fails, confirm the repository is linked to the right project and that you have whatever credentials the Supabase workflow needs to apply migrations.
Runtime configuration issues
If the packaged app does not connect on first launch, assume the runtime bootstrap step did not complete. Re-run the configuration or installation workflow and then relaunch the app.
Why Polter is required
Short answer
Because Ops no longer treats Supabase workflows as app CLI responsibilities. Polter is the supported workflow layer for those jobs, and the documentation assumes that split.