code, title and message, plus a fields map on a 422. Codes are NRY- and four digits. Quote the code when you report a problem. The host API overview describes the transport these answers arrive on.
{ "code": "<code>", "title": "<title>", "message": "<message>" }
Codes the host answers
The
message always names the specific thing that failed. Read it before you act on the row below.
| Code | HTTP status | When the host answers it | What to do |
|---|---|---|---|
| NRY-0000 | 400 | The request is malformed. The body is not valid JSON, or a value does not bind to its declared type. | Correct the request encoding. The message names the part that failed to bind. |
| NRY-0001 | 422 | A request body failed validation. | Correct the properties the fields map names, then send the request again. |
| NRY-0002 | 404 | No session on this host carries the sessionId in the request. | List sessions to get a valid id. |
| NRY-0003 | 409 | The target session is archived. An archived session accepts no new work. | Branch the session at an entry to continue from its transcript, or address an active session. |
| NRY-0004 | 409 | The target session or lane cannot accept the request in its current state. | Wait for the work in flight to finish, or interrupt it, then send the request again. |
| NRY-0006 | 409 | Two packages claim the same replaceable slot. Nothing was installed. A package job that fails this way carries the code in its error field. | Remove or disable one claimant, then install again. The message names both. |
| NRY-0007 | 409 | A package build failed. The binary that was already serving is intact. A package job that fails this way carries the code in its error field. | Read the job’s error, correct or remove the package, then install again. |
| NRY-0009 | 404 | The addressed peer session is gone from this host. | List peers to refresh the set of addressable sessions, then send the message again. |
| NRY-0010 | 422 | A workflow script failed validation before the run started. | Correct the script errors the message names, then start the run again. |
| NRY-0012 | 500 | The local store is unavailable, or it failed its integrity check. The host refuses writes rather than work on a damaged store. | Check disk space and store integrity, correct the cause, then restart the host. |
| NRY-0015 | 404 | The named resource does not exist on this host. Packages, package jobs, agent recipes, skills, commands, lanes, monitors, providers, schedules, workflow runs, inter-session asks and transcript entries all answer with this code. | List the collection the resource belongs to, and use a name or id from it. |
| NRY-0016 | 409 | A package with this name is already installed. | Remove the installed package first, or install under another name. |
| NRY-0017 | 409 | An enable or a disable swapped the binary, and then failed to confirm the package row. | The change already applies to the binary that runs now. Send the request again, or restart the host so start-up reconciliation confirms the row. |
| NRY-0020 | 412 | A conditional write carried an ifMatchesSha256 that the stored value no longer hashes to. Another client wrote the row first, and nothing was written. | Read the resource again to see what it holds now. A client that clears a draft it sent can treat this as success. |
| NRY-0021 | 500 | The host could not carry out the request on this machine. A process it had to start did not start, or an operation failed for a reason with no more exact code. | Nothing about the request was wrong, so send it again. The host log carries the cause, which the message leaves out. |
| NRY-0022 | 500 | A rewind that restores named files stopped part-way. Some files are back and the rest are untouched. | Read the message for the files that moved. The working tree as it stood before the attempt is kept as a restore point. |
| NRY-0023 | 500 | A rewind of the conversation and the files branched the conversation, and then failed to restore the files. The branch is real. | Continue in the session the message names, then rewind the files alone from the original session at the same moment. |
| NRY-0024 | 413 | A transcript import ran past a size ceiling. | Read the message for the ceiling it names, then send a smaller transcript. |
| NRY-0025 | 409 | A blocking ask between sessions was refused, because granting it would close a loop of sessions that wait on each other. | Answer or expire the ask already in flight, or send a one-way message instead. The message names both sessions. |
| NRY-0026 | 409 | A stream resumed from a Last-Event-ID that names an event newer than anything this store holds. | Resume with no Last-Event-ID, then read state again through the GET operations. The same cursor is refused identically every time. |
| NRY-0027 | 413 | The files on one message weigh more together than one supplier request can carry. Nothing was written. | Send fewer files on the message, or smaller ones. The message names the ceiling in bytes. |
Codes a failed turn carries
A turn that fails ends with a
turn-finished event. Its payload.error carries the same envelope as an HTTP error. Three codes arrive that way, and the host never answers them as an HTTP status.
| Code | Event | When the host writes it | What to do |
|---|---|---|---|
| NRY-0008 | turn-finished | The model supplier the turn needed has no usable credential. It is missing, expired or refused, or the keyring is unavailable. | Sign in with narya auth login <provider>, then send the message again. The message names the remedy that fits. |
| NRY-0018 | turn-finished | The turn could reach no model supplier. The session names no provider, or it names one this host has no record of. | Sign in with narya auth login <provider>, or set default_model in the host’s config.toml, then send the message again. narya providers lists what this machine can use. |
| NRY-0019 | turn-finished | The turn failed for a reason with no more specific code. The message carries the cause. Narya removes known credential shapes and URL secrets from it, and replaces your home directory with ~. Host paths outside your home stay. | Read the message. The host log carries the same failure without the redaction. |