Troubleshooting
Find your error below. For SQL limitations, see the SQL companion.
What went wrong?
| Problem | What to try |
|---|---|
| Missing URL, account or driver | For a local install, use the Run locally page. For an existing instance, use the supplied connection details. SQL Editor needs no JDBC; see connection options. |
| Local install won't start | Run preflight.sh from the platform bundle and follow the install guide. Check registry access, memory, disk and configuration. |
| Login fails or HTTP 401 | Check the URL and credentials. Changing the platform's .env after setup does not reset an account. |
REST preflight says Operation not permitted for localhost |
The command environment may have blocked local network access before Zetaris returned an HTTP response. In Codex, retry the read-only command with the requested network or elevated execution permission if offered. Do not change the API URL or key based on this error. If permission is unavailable, run the command in a terminal that can reach the instance. |
| Permission error or HTTP 403 | Check your organisation, team names and account permissions. Use your own account. |
| Missing or invalid org ID | Follow HTTP setup and use your numeric ID. SQL Editor does not need this setting. |
| HTTP 404 or an HTML response | Use the UI URL that supports the helper's proxy routes. The raw API port does not. |
| JDBC won't connect | Check the driver JAR, class, Java and endpoint. On a remote agent, localhost is that machine. |
| Object already exists | Check its owner and definition. Reuse a match; otherwise use your assigned team name. |
| Table created but no rows returned | Check the source path, response, schema and Zetaris access. Start with a small SELECT. |
| HTTP 429 | Wait as the source instructs. For company_dns, wait 60 seconds and retry that one statement. Space endpoint calls by at least 15 seconds and cache the raw table. Avoid retry loops; one statement can trigger several requests. |
| HTTP 502 | Check the source error and retry once if appropriate. company_dns has moved hosts and no longer uses the removed warm-up helper. On rate-limited sources, wait before another attempt. Report repeated failures. |
| PUDL registration fails | PUDL has a known issue. Use the PokéAPI starter. |
| A downloaded file won't query | Put it in storage Zetaris can reach. A file on your laptop may be out of reach. |
| Chart won't read the result | Check the query response shape and look for an error before comparing it with the example. |
Reruns and team isolation
On the shared instance, use your assigned team names. Names help avoid clashes; permissions control access.
- Replace all database, container, namespace, model and reference names consistently.
- Check existing objects before creating them. See the recipe reference.
- Reuse shared sources only when their definitions and your read permission are confirmed.
- Run one complete statement at a time. If one fails, fix it and continue; earlier statements may have created objects.
- Cache, change or remove only objects you own and are allowed to change.
run_sql.py --skip-exists skips duplicate errors. It does not check that an existing object matches your recipe. CREATE SCHEMASTORE CONTAINER has no IF NOT EXISTS; check before creating another container. See the SQL companion for the tested cleanup scope.
Cleanup
Remove only objects you own and have permission to remove. Do not stop or reset the shared platform. For your local install, follow the installation guide's shutdown steps.
On 12 October 2026, Zetaris 2.4.3.1 let DROP LIGHTNING DATABASE TABLE remove reason (public S3 filestore) and ability (PokéAPI REST); DROP LIGHTNING DATABASE then removed their test database. This covers only these fixtures. The check deleted an empty SchemaStore container through the documented API after viewCount=0; no SQL container-drop form was tested. Use Data Explorer's File Source & API panel for other registrations. See the SQL companion for full scope.
Only drop a namespace if you may remove everything it contains.
Record the error
Report the tool, failed step, time, error and last step that worked. State whether login, SQL and source queries worked. Remove passwords, tokens, Authorization headers and unrelated customer data.