> ## 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**, so 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 `''`, because 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, because 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

Every error returns `{ "error": { "code": "...", "message": "..." } }`. The code table and the rate
limit are in the [Database API overview](/api/overview#errors).

## 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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.