Troubleshooting - Zite Platform

Errors are grouped by where they happen: while an agent builds, at runtime, and at the Database API.

While building (Zite MCP)

Symptom	Cause & fix
`edit_file` fails: oldText not found / matches N places	`edit_file` needs `oldText` to appear exactly once. Include more surrounding context so the match is unique, or use `read_file` to copy the current text precisely.
`commit` returns a push conflict (409)	The remote has newer commits. Run `git pull --rebase origin main` via `bash`, resolve conflicts, then `commit` again.
`publish_app` fails: build still running / failed	Publishing requires a successful build. Wait for the background build to finish, or fix errors with `check_app` / `get_logs` and `commit` again.
Frontend can’t import a new workflow	Run `npx zitejs generate` from the workspace root after adding, renaming, or deleting workflow files. `check_app` and `commit` also run it. Running it from inside an app dir silently generates nothing.
Editing `.zite/` has no effect (or breaks types)	`.zite/` files and `src/main.tsx` are generated — never edit them. Change the schema or workflows and regenerate.

At runtime

Symptom	Cause & fix
Aggregates / counts are wrong on large tables	`findAll` caps at 2,000 rows, so JS-side sums/counts undercount. Use `zite.sql()` for aggregates, joins, and group-bys.
`zite.sql()` error: invalid input syntax for type timestamp: ""	Never compare a date field to `''` — empty dates are `NULL`. Use `WHERE "dueDate" < CURRENT_DATE` (which already skips unset rows), not `NULLIF("dueDate", '')`.
`zite.sql()` error: relation “orders” does not exist	Unquoted identifiers are lowercased by Postgres. Double-quote every table/field SDK name: `FROM "Orders"`, not `FROM Orders`.
`zite.sql()` error: operator does not exist: jsonb = uuid	A `linked_record` is JSONB, not a foreign key. Join through the link table (`"ItemsOrders"` with id columns `"itemsId"`/`"ordersId"`), not on the field directly.
A scheduled job never fires, or fires at the wrong time	Don’t simulate cadence with `setInterval`/`setTimeout` or in-code skip checks — serverless runs don’t keep timers alive. The workflow’s `schedule` field is the only source of truth. See Scheduled jobs.
`context.user` is `null` in a workflow	Expected on scheduled and anonymous fires. Set `authenticated: true` and require sign-in if you need a user. See Auth.
An integration call fails with a missing token	The integration isn’t connected. Connect it (the agent hands you a `setup_integration` link), then the `ZITE_<SERVICE>_ACCESS_TOKEN` is available. See Integrations & secrets.

Database API errors

All Database API errors return { "error": { "code": "...", "message": "..." } }:

Code	Meaning
`INVALID_RECORD_ID`	Record ID is not a valid UUID
`NOT_FOUND`	The resource doesn’t exist
`BAD_REQUEST`	Invalid request data or validation failure
`UNAUTHORIZED`	Invalid or missing API key
`NOT_IMPLEMENTED`	Feature not yet implemented
`INTERNAL_SERVER_ERROR`	Server-side error

Requests are limited to 30 per second per database; the response includes RateLimit-* headers — back off when you approach the limit. See the Database API overview.

Limits

The full platform limits table (result-set caps, timeouts, payload sizes, retention) is on Platform limits.

Building with an agent? After a change, ask it to exercise the affected workflow and pull get_logs — most runtime errors above only surface when the code actually runs, not from a type-check.