# Errors > Every kind of error the engine and the MCP server answer, with its status, what its hint gives and the page its docs link names. Every error of the engine says three things: what is wrong (`error`), how to fix it (`hint`) and where to read more (`docs`, a page of this site in Markdown, with its anchor). The HTTP API sends them as JSON fields; the MCP server and `DatanotesError` end the text with a `Hint:` and a `Docs:` line. The docs line of `DatanotesError` gives the address, then the `read_docs` call that reads the same section offline; `datanotes mcp` gives only the call: ```text insert_row refused — nothing was written: invalid datanotes/main/public/film/Sunrise.md: status must be one of: to watch; watched Hint: Use one of the allowed values listed in the message, written exactly; describe_table shows what each one means. To add a value, alter_column the enum. Docs: https://datanotes.dev/guides/database-objects/columns.md#describe-what-each-enum-value-means (offline: read_docs("guides/database-objects/columns#describe-what-each-enum-value-means")) ``` [Read the engine’s errors](https://datanotes.dev/guides/agents/reading-errors/) shows how an agent uses them. ## Kinds of error | Error | Status | The hint gives | Docs | | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Unknown tool or operation | MCP tool error; 400 | The closest tools | [Operations](https://datanotes.dev/reference/operations/) | | Argument unknown, missing or of the wrong type | MCP tool error, before the call | The argument meant, and the tool’s arguments with their types | The operation’s reference | | Bad input to an operation or a route | 400 | Its own where the answer is data, else the operation’s arguments | The topic’s page, or the operation’s reference | | Table or view not found | 404 | The closest names and aliases, the tables and views, or the view’s table where a table is needed | [Find the table that matches a request](https://datanotes.dev/guides/database-objects/tables/#find-the-table-that-matches-a-request), [Store a query as a view](https://datanotes.dev/guides/database-objects/views/#store-a-query-as-a-view) | | Ambiguous table name | 409 | The full names | [Place tables in catalogs and schemas](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/#place-tables-in-catalogs-and-schemas) | | Unknown column | 400 | The closest column, the table’s columns, `describe_table` and `add_column` | [Describe a table before writing to it](https://datanotes.dev/guides/database-objects/tables/#describe-a-table-before-writing-to-it) | | Unknown filter operator | 400 | The operator meant, every operator, and the shape of a condition | [Compare values with operators](https://datanotes.dev/guides/read-and-write/read-and-filter/#compare-values-with-operators) | | Bad expression or aggregate | 400 | The columns and the shape | [Group rows and compute totals](https://datanotes.dev/guides/read-and-write/joins-and-aggregates/#group-rows-and-compute-totals) | | Unknown base, constraint, catalog, schema, enum value or link column | 400 | The closest name, the list, and the operation that lists them | The topic’s page | | A name that isn’t an identifier | 400 | The name it could be | [Place tables in catalogs and schemas](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/#place-tables-in-catalogs-and-schemas) | | A table, base or column without a description, or one removed | 400 | Every missing description, and the call’s shape with each in place | [Describe every table and column](https://datanotes.dev/guides/database-objects/tables/#describe-every-table-and-column) | | Row not found | 400 | The closest note name, and how to find a row’s `path` or `id` | [Update one row](https://datanotes.dev/guides/read-and-write/write-rows/#update-one-row) | | A value breaks a rule (a violation) | 422 | The hint of its kind: [Violations](#violations) | The page of its kind | | A conflict: `expect`, linked rows, rows that break a new CHECK, a column others read, `cascade`, a name taken, merge keys | 422 | What the conflict means and what to do | [Guard a write against concurrent edits with `expect`](https://datanotes.dev/guides/read-and-write/write-rows/#guard-a-write-against-concurrent-edits-with-expect), [Delete a row that other notes link to](https://datanotes.dev/guides/database-objects/relations/#delete-a-row-that-other-notes-link-to), [Enforce rules with CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/#enforce-rules-with-check-constraints), [Drop a table and archive its rows](https://datanotes.dev/guides/database-objects/tables/#drop-a-table-and-archive-its-rows), [Insert or update rows with `merge_rows`](https://datanotes.dev/guides/read-and-write/write-rows/#insert-or-update-rows-with-merge_rows) | | A write that failed partway, rolled back by the engine | 503, with the result as the body | Free the file, then send the write again | [The engine rolls back a write it cannot finish](https://datanotes.dev/guides/history/journal-and-undo/#the-engine-rolls-back-a-write-it-cannot-finish) | | A write that failed partway, and its rollback too | 500, with the result as the body | `undo_migration` | [Undo a write](https://datanotes.dev/guides/history/journal-and-undo/#undo-a-write) | | Undo refused, or migration not found | 409, 404 | Undone already, the later changes, `list_migrations` | [Undo a write](https://datanotes.dev/guides/history/journal-and-undo/#undo-a-write), [Undo refuses to overwrite later changes](https://datanotes.dev/guides/history/journal-and-undo/#undo-refuses-to-overwrite-later-changes) | | No history, no such version, a time before the table existed | 400 | `alter_table` with `history: "on"`, `describe_history`, `timestamp` | [Turn history on for a table](https://datanotes.dev/guides/history/table-history/#turn-history-on-for-a-table), [List the versions of a table](https://datanotes.dev/guides/history/table-history/#list-the-versions-of-a-table) | | A batch with an operation refused or unknown | 422, 400 | Each operation’s own; fix it and send the whole batch again | [Group several writes with `batch`](https://datanotes.dev/guides/read-and-write/batch/#group-several-writes-with-batch) | | A token beyond its permissions | 403 | The permissions, and who changes them | [Choose what a token can do](https://datanotes.dev/guides/security/tokens/#choose-what-a-token-can-do) | | Token missing or wrong | 401 | Which token to send, as a bearer token | [Authenticate your requests](https://datanotes.dev/develop/http-api/#authenticate-your-requests) | | Unknown operation, route, argument, method or body | 404, 400, 405 | The closest operation, route or argument, and the routes in `openapi.json` | [Call the engines routes](https://datanotes.dev/develop/http-api/#call-the-engines-routes) | | Note or folder not found | 404 | Vault paths, `list_folder` and `search_notes` | [Read a note](https://datanotes.dev/guides/search/text/#read-a-note) | | Change feed, webhooks or semantic search off | 400, 503 | How to turn it on | [Follow every change with the change feed](https://datanotes.dev/guides/history/change-data-feed/#follow-every-change-with-the-change-feed), [Turn on semantic search](https://datanotes.dev/guides/search/semantic/#turn-on-semantic-search) | | Engine unreachable | Thrown by the client; 502 from the MCP server | Start the engine, or check its address | [How the mcp server reaches the engine](https://datanotes.dev/start/connect-agents/#how-the-mcp-server-reaches-the-engine) | | The engine can’t listen: a port in use or reserved, an address of another machine | Exit code 1 of `datanotes serve` | Another `--port`, `--port 0`, or an address of this machine | [Choose the port](https://datanotes.dev/administration/run-the-service/#choose-the-port) | | A request while the engine stops | 503 | Wait for the stop, then start the engine again | [Stop the engine](https://datanotes.dev/administration/run-the-service/#stop-the-engine) | | Unexpected error | 500 | None: it isn’t a mistake of the caller | None | A refused write writes nothing, so the caller can fix the call and send it again. Hand edits that break a rule aren’t errors: `check_table` and the change feed report them as violations. ## Violations A write the engine refuses lists its violations, each with a `code`; `check_table` and the change feed report the violations of hand edits with the same codes. | Code | Hint | Docs | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `required` | Give a value to every required column; describe_table marks them (required: true) and lists an enum’s values. | [Describe a table before writing to it](https://datanotes.dev/guides/database-objects/tables/#describe-a-table-before-writing-to-it) | | `type` | Give each value the column’s type (describe_table shows it): numbers unquoted, dates as YYYY-MM-DD, links as “\[\[Note]]”, lists as JSON arrays. | [Create a table with typed columns](https://datanotes.dev/guides/database-objects/tables/#create-a-table-with-typed-columns) | | `enum` | Use one of the allowed values listed in the message, written exactly; describe_table shows what each one means. To add a value, alter_column the enum. | [Describe what each enum value means](https://datanotes.dev/guides/database-objects/columns/#describe-what-each-enum-value-means) | | `vocabulary` | Use one of the values listed in the message, or first insert the new value as a row of the vocabulary table. | [Take allowed values from another table](https://datanotes.dev/guides/database-objects/relations/#take-allowed-values-from-another-table) | | `min` | Give a value inside the column’s range (the message names the bound); describe_table shows its min and max. | [Describe a table before writing to it](https://datanotes.dev/guides/database-objects/tables/#describe-a-table-before-writing-to-it) | | `max` | Give a value inside the column’s range (the message names the bound); describe_table shows its min and max. | [Describe a table before writing to it](https://datanotes.dev/guides/database-objects/tables/#describe-a-table-before-writing-to-it) | | `step` | Give a multiple of the column’s step (describe_table shows it). | [Describe a table before writing to it](https://datanotes.dev/guides/database-objects/tables/#describe-a-table-before-writing-to-it) | | `broken_link` | Link to a note that exists, as “\[\[Note name]]”: list_link_targets(table, column) lists the rows the column may point to. | [Point a column to a row of another table](https://datanotes.dev/guides/database-objects/relations/#point-a-column-to-a-row-of-another-table) | | `ref` | Link to a row of the table the column points to (its ref) that its ref_where / ref_by allow: list_link_targets(table, column) lists them. | [Limit link targets with `ref_by` and `ref_where`](https://datanotes.dev/guides/database-objects/relations/#limit-link-targets-with-ref_by-and-ref_where) | | `unique` | Another row already has this value: choose another one, or update that row instead (select_rows finds it). | [Update one row](https://datanotes.dev/guides/read-and-write/write-rows/#update-one-row) | | `unknown_column` | Write only the table’s columns: describe_table lists them. To keep a new front matter key, add_column first. | [Describe a table before writing to it](https://datanotes.dev/guides/database-objects/tables/#describe-a-table-before-writing-to-it) | | `check` | The row breaks a CHECK constraint of the table (named in the message, with its rule): change the values so the rule holds. describe_table lists the table’s constraints. | [Enforce rules with CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/#enforce-rules-with-check-constraints) | | `generated` | A generated column is computed by the engine: do not write it; recompute_columns sets it again. | [Recompute generated columns after a hand edit](https://datanotes.dev/guides/data-quality/hand-edits/#recompute-generated-columns-after-a-hand-edit) | | `cycle` | A row cannot be its own ancestor: point the hierarchy column to a row that is not below this one. | [Build a tree of rows with a parent link](https://datanotes.dev/guides/database-objects/relations/#build-a-tree-of-rows-with-a-parent-link) | | `inverse` | Both sides of a two-way link must agree: write one side, or run align_relations to repair them. | [Repair two-way links with `align_relations`](https://datanotes.dev/guides/database-objects/relations/#repair-two-way-links-with-align_relations) | | `unreadable` | The note’s front matter is not valid YAML (the message quotes the parser), so every read leaves the row out: open the note and fix the YAML, such as a quote or bracket left open or a line without `key: value`. read_note shows its text. | [Find rows whose front matter can’t be read](https://datanotes.dev/guides/data-quality/hand-edits/#find-rows-whose-front-matter-cant-be-read) |