--- title: Errors --- # Errors When something goes wrong, String tells the AI what happened and what it can do about it. Errors are plain text — readable, actionable, and consistent across all commands. --- ## Error format Every error follows the same structure: ``` ✗ ERROR_CODE: message context ``` - **`✗`** — error indicator (vs `✓` for success) - **Error code** — machine-readable identifier - **Message** — human-readable description - **Context** — actionable details (available options, suggestions) --- ## Error codes ### Navigation errors **NOT_FOUND** — the topic does not exist. ``` /open ~/docs/missing.md ``` ``` ✗ NOT_FOUND: file not found path: ~/docs/missing.md ``` ``` /open @nonexistent ``` ``` ✗ NOT_FOUND: shortcut not found @nonexistent is not defined in this document available: @docs, @pricing, @main.home, @main.api ``` **BLOCK_NOT_FOUND** — the file exists but the block doesn't. ``` /open ~/docs/report.md#missing ``` ``` ✗ BLOCK_NOT_FOUND: block #missing not found in ~/docs/report.md available blocks: #summary, #details, #appendix ``` --- ### Editing errors **INVALID_PATH** — the path is malformed or outside workspace. ``` /write /etc/passwd ``` ``` ✗ INVALID_PATH: path is outside workspace boundary workspace: ~/ requested: /etc/passwd ``` ``` /write ../../../etc/shadow ``` ``` ✗ INVALID_PATH: path traversal not allowed resolved: /etc/shadow (outside workspace) ``` **LINE_OUT_OF_RANGE** — line number doesn't exist. ``` /replace ~/docs/report.md:L500 new content ``` ``` ✗ LINE_OUT_OF_RANGE: line 500 does not exist ~/docs/report.md has 42 lines ``` **CONFLICT** — the file was modified externally since last read. ``` /replace ~/docs/report.md#summary new summary ``` ``` ✗ CONFLICT: file has been modified since last read expected: hash abc123 current: hash def456 use /refresh to reload, then retry ``` --- ### Action errors **ACTION_NOT_FOUND** — the action is not defined in the current document. ``` /act.nonexistent --flag value ``` ``` ✗ ACTION_NOT_FOUND: action nonexistent is not defined available actions: search_city, create_alert ``` **INVALID_PARAMS** — required parameters missing or invalid. ``` /act.search_city ``` ``` ✗ INVALID_PARAMS: missing required parameter name: string (required) — not provided usage: /act.search_city --name "{City Name}" ``` ``` /act.create_alert --condition "earthquake" ``` ``` ✗ INVALID_PARAMS: invalid value for condition expected: rain|snow|temp received: earthquake ``` **ACTION_FAILED** — the action executed but the backend returned an error. ``` /act.search_city --name "Atlantis" ``` ``` ✗ ACTION_FAILED: upstream error (404) GET https://api.weather.com/search?name=Atlantis response: city not found ``` --- ### Variable errors **INVALID_VARIABLE** — `$` variable used in AI command. ``` /act.search --key $API_KEY ``` ``` ✗ INVALID_VARIABLE: runtime variable $API_KEY cannot be used in commands $variables are only allowed in document action definitions ``` **UNDEFINED_VARIABLE** — referenced variable has no value. ``` /act.get_repos --token {token} ``` ``` ✗ UNDEFINED_VARIABLE: {token} is not defined in current session use /set or an action response template to define it ``` --- ### Command errors **COMMAND_UNSUPPORTED** — input does not start with `/`. ``` <𝒞=string:file:main> hello world ``` ``` ✗ COMMAND_UNSUPPORTED: Commands must start with /. Use /help for details. ``` All input must be a command. Plain text is not accepted. --- ### Session errors **INVALID_TARGET** — the topic identifier is malformed. ``` <𝒞=string:intro.md> /open index.md ``` ``` ✗ INVALID_TARGET: invalid topic "intro.md" format: type:name (e.g. file:main, web:docs, app:weather) names: [a-zA-Z0-9_-]+ only — no dots, no paths ``` **NO_HISTORY** — `/back` with nothing to go back to. ``` /back ``` ``` ✗ NO_HISTORY: no previous location in this topic ``` --- ### Version errors **NO_COMMITS** — `/log` on a file with no commits. ``` /log ~/docs/new-file.md ``` ``` ✗ NO_COMMITS: ~/docs/new-file.md has no commit history use /commit to create the first snapshot ``` **VERSION_NOT_FOUND** — requested version doesn't exist. ``` /open ~/docs/report.md@c99 ``` ``` ✗ VERSION_NOT_FOUND: version c99 not found latest: c3 use /log ~/docs/report.md to see available versions ``` --- ## Error code reference | Code | When | |------|------| | `NOT_FOUND` | File, URL, or shortcut doesn't exist | | `BLOCK_NOT_FOUND` | Block ID not in document | | `INVALID_PATH` | Path outside workspace or malformed | | `LINE_OUT_OF_RANGE` | Line number exceeds file length | | `CONFLICT` | File modified externally since last read | | `COMMAND_UNSUPPORTED` | Input doesn't start with `/` (plain text rejected) | | `ACTION_NOT_FOUND` | Action not defined in document | | `INVALID_PARAMS` | Missing or invalid action parameters | | `ACTION_FAILED` | Backend returned an error | | `INVALID_VARIABLE` | `$var` used in AI command | | `UNDEFINED_VARIABLE` | `{var}` has no value in session | | `INVALID_TARGET` | Topic identifier malformed (dots, paths, unknown type) | | `NO_HISTORY` | No previous location for `/back` | | `NO_COMMITS` | No version history for file | | `VERSION_NOT_FOUND` | Requested version doesn't exist | | `LOAD_ERROR` | Network or I/O failure loading content | | `AUTH_REQUIRED` | Topic requires authentication | --- ## How AI should handle errors ### Read and retry Most errors include enough context to fix the issue: ``` ✗ BLOCK_NOT_FOUND: block #sumary not found available blocks: #summary, #details → AI sees the typo, retries with #summary ``` ### Fall back When an action fails, try an alternative path: ``` ✗ ACTION_FAILED: upstream error (503) → /back and try a different approach → or /refresh and retry later ``` ### Ask for help When the error is about permissions or missing configuration: ``` ✗ AUTH_REQUIRED: https://api.example.com requires authentication → AI reports to user that authentication is needed ``` --- ## Design principles **Errors are text.** Not JSON error objects, not HTTP status codes wrapped in XML. Plain text that any AI can read without a parser. **Errors are actionable.** Every error includes context that helps the AI fix the problem — available blocks, correct syntax, valid options. The AI shouldn't need an extra round trip to figure out what went wrong. **Errors are consistent.** Same format across all commands. The AI learns one error pattern and it works everywhere. --- ## Summary | Principle | How | |-----------|-----| | **Format** | `✗ CODE: message` + context | | **Context** | Available options, correct syntax, suggestions | | **Actionable** | AI can fix and retry without extra round trip | | **Consistent** | Same structure for all commands | | **Plain text** | No special parsing needed |