> ## Documentation Index
> Fetch the complete documentation index at: https://developers.zite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common failure modes when building and running Zite apps, and how to fix them — for developers and agents.

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()`](/recipes/dashboards-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](/recipes/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](/framework/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](/concepts/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](/api/overview).

## Limits

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

<Tip>
  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.
</Tip>