docs/generated/errors.mdgenerated from code
Use · 13 min read
Errors and recovery
Every error code, rule, and recovery, as agentflare explain prints them.
Every JSON-RPC error the daemon answers carries data with a reason, a recover kind, and, unless recover is none, the one next step to take; a refusal by a rule names the rule. agentflare explain <value> prints any entry on this page, offline.
Error codes
What went wrong with a request, as the JSON-RPC error's code (its number) and message. Every error's data also says how to recover (a recover value) and, unless that is none, the one next action to take.
parse_error
The request line is not JSON, or not UTF-8 text. Send one JSON object per line.
Number -32700, message "parse error". Recover: fix_request.
invalid_request
The line is JSON but not a JSON-RPC 2.0 request: it lacks jsonrpc, method, or id, or is longer than the daemon reads.
Number -32600, message "invalid request". Recover: fix_request.
method_not_found
No operation has this name. The op vocabulary lists every operation.
Number -32601, message "method not found". Recover: fix_request, none.
invalid_params
The operation exists, but its params don't fit it: a field is missing, has the wrong type, or is out of range.
Number -32602, message "invalid params". Recover: fix_request.
internal_error
The daemon failed to finish the request. A transient fault (a part of the daemon not yet running) clears on a retry; a corrupt stored document needs manual repair; a daemon bug does not.
Number -32603, message "internal error". Recover: retry_after, wait, fix_request, none.
no_peer
The connection has not said which peer it acts for: the first request on a connection must be hello, with a peer this daemon knows and the connecting OS user may act as.
Number -32001, message "no peer". Recover: join, wait, fix_request.
unknown_base
The request is based on a version of the document this daemon doesn't have. Read the document again and redo the change from what it holds now. A read at a frontier that holds no such file (discussion:owner/385) is this code too, recovered by fixing the request.
Number -32002, message "unknown base". Recover: rebase, fix_request.
out_of_bounds
A change reaches past the end of the document at the version it is based on. Read the document again and redo the change from what it holds now.
Number -32003, message "out of bounds". Recover: rebase.
rejected
A rule refused the request: the error's rule names which one, and its recovery is that rule's.
Number -32004, message "rejected". Recover: ask, renew, fix_request, wait, tree_file, none, rebase.
rate_limited
The peer sent requests faster than its rate allows. Wait the time the error gives, then send the same request again.
Number -32005, message "rate limited". Recover: retry_after, fix_request.
secret_detected
The change looks like it holds a secret (a key, a token, a password), so it was held and not shared. Confirm it holds none, or change the request so it doesn't.
Number -32006, message "secret detected". Recover: force, fix_request.
path_collision
The path collides with another one that differs only by letter case or Unicode normalization, or names an existing directory. Choose another path.
Number -32007, message "path collision". Recover: fix_request.
unknown_node
The node the request names isn't connected to this daemon's project swarm (discussion:owner/400). Name a node node.list lists.
Number -32008, message "unknown node". Recover: fix_request.
not_supported
The node the request names doesn't speak the protocol the request needs (discussion:owner/400): it runs an older LVCS. Upgrade LVCS on that machine.
Number -32009, message "not supported". Recover: upgrade, fix_request.
Rules
Which rule refused a request: the error's data.rule, present exactly when its code is rejected. Each rule has one recovery.
out_of_scope
No grant the peer holds covers this path or operation.
Recover: ask.
grant_ended
The grant that covered the request has expired or was revoked.
Recover: renew.
quota_spent
The peer has used up the number of changes its grant allows.
Recover: renew.
protected_path
The path is protected: a change to it reaches others only after checks pass and a holder of the approve capability approves it.
Recover: fix_request.
unattested
The version the request names has not passed the project's checks yet.
Recover: wait.
policy_unknown
The project's rules for this path are not known yet on this daemon, because its grants have not synced.
Recover: wait.
not_synced
The path is never shared: a control document under .lvcs/, a path the project never syncs (a .gitignore or .lvcsignore ignores it, or it is never-sync), a link or special file on the path, or a path outside every tree directory.
Recover: fix_request.
not_author
Only the peer whose change is held may do this.
Recover: ask.
tree_file_author
The tree directory writes as another peer, so this peer may not write through it.
Recover: tree_file.
not_a_repository
Never answered by this release: the lvcs binary reads and writes no git repository (discussion:owner/456). It stays in the set because the JSON-RPC API is compatible from v0.1.0.
Recover: none.
outcome_unknown
An earlier request with the same request id is still running or its answer was lost, so whether it applied is unknown. Read the document again and redo the change from what it holds now.
Recover: rebase.
no_action
run names no gated action: no approved [[actions]] entry in lvcs.toml with on = "manual" or on = { channel = ... } has that name (a change action runs on every change to main, never by run). Run an action the approved lvcs.toml gates, or add one and have its lvcs.toml change approved first.
Recover: fix_request.
not_eligible
The frontier run names can't be run on by this action yet: its after channel doesn't hold it, and the action's channel holds no passed run of it; or no frontier was named and the after channel holds none, or several. Read the after channel to see which frontiers it holds, then wait for this one or name one it holds.
Recover: wait.
superseded
The frontier run names is behind the action's channel: the channel's value is a newer frontier that holds all of it, and the channel never passed a run of it, so running it would move the channel backward (discussion:owner/306). Read the channel and run the action on its value or a newer frontier; a rollback names a frontier the channel passed before.
Recover: fix_request.
git_rewrite
Never answered by this release: LVCS maps no git branch ( discussion:owner/456). It stays in the set because the JSON-RPC API is compatible from v0.1.0.
Recover: fix_request.
action_refused
The approval would put in force a set of actions that is refused: two declarations of one action, a GitHub workflow job LVCS can't run, or an lvcs.toml whose channel triggers name an unknown channel or form a cycle, which the reason names (reason names the action_refusal value). Fix the file, or list the job in lvcs.toml's [workflows] skip, as the reason says, and approve again.
Recover: fix_request.
stale_overlap
A tree save or an edit was made from an older version of the file than the one it now holds, and the lines it changes overlap lines another peer changed since that version ( discussion:owner/296 and 310). It was not taken, and the file now holds the current version: read it again and redo the change from what it holds now. The reason names the overlapping lines and who changed them.
Recover: rebase.
unproven_base
A tree save that no hook proved was read from a version of the file (a shell write, or an Edit whose read was lost) would replace or delete lines, and with no read proving which version its buffer held, that could revert a newer version, whoever wrote the lines (discussion:owner/732). It was not taken, and the file keeps its bytes, held back: make the change with the Edit tool after a Read, or land the bytes against main's heads (agentflare read --heads, then agentflare write --base).
Recover: rebase.
not_durable
No document took a tree save while another save of the file was still out (discussion:owner/439), so its change was never committed, and the disk's bytes can't be saved again from a version no peer's change has moved past. The file keeps its bytes, held back: land them against main's heads (agentflare read --heads, then agentflare write --base).
Recover: rebase.
device_scope
A paired device may not do this (discussion:owner/300): a read device only reads, a write device also coordinates (asks, answers, holds, says, runs gated actions), and no device edits files. Pair a device with the scope it needs (agentflare auth login --write), or do it from an agent or the CLI.
Recover: fix_request.
change_too_large
A save or an edit would make one change larger than CHANGE_MAX_BYTES (discussion:owner/611): no sync envelope could carry it, so it would never reach another node. It was not taken, and a tree save stays held. Ignore the file (.gitignore or .lvcsignore) if it is a build artifact, or split the edit.
Recover: fix_request.
purged
The file's document was purged from the project by its owner (discussion:owner/614): every honest node dropped its content and refuses every read, sync, and restore of it. Nothing brings it back; name another file.
Recover: fix_request.
nodes_behind
A connected node runs an lvcs release whose checks would refuse this change for good (discussion:owner/614): nothing was committed. Wait until every node the reason names runs the release it names, then ask again.
Recover: wait.
not_authorized
Only the one process the op belongs to may ask it: a plugin's serve its keeper started, as the plugin's own key, says it is dormant (discussion:owner/790). Nothing changed; ask it from that process.
Recover: fix_request.
Recovery kinds
How to recover from an error: the error's data.recover. Unless it is none, the error's data.next holds one concrete action that does it: an operation with its params, the same request sent again, or an lvcs command line.
wait
Wait for something outside the caller to change (an attestation, a sync, a grant), then try again.
retry_after
Send the same request again after the time the error gives, in data.retry_after_ms.
rebase
Read the document again and redo the change from what it holds now.
ask
Ask a peer who can allow it: the owner, or the issuer of the grant the request needs; for a node whose release is older than this daemon's, its owner to upgrade.
yield
Give up what the caller holds there (an announced project), and act elsewhere.
force
The flagged text holds no secret: save the file with agentflare add --force <path>, which records a signed allowlist entry (discussion:owner/513).
renew
Get the grant renewed, or a new grant, from its issuer.
tree_file
Open a main tree of your own (tree_file.open) and write through it: its saves are signed as you (discussion:owner/221).
join
Join the project as a peer first.
fix_request
Change the request itself: its parameters, its path, or its operation.
redo
A stored change can't be applied because a change it depends on was never stored here: it is set aside unchanged, and the write it made has to be made again (secfix/31).
upgrade
An LVCS-owned file under .lvcs/ has a newer format than this lvcs reads, or a node speaks a newer wire major than this daemon: install a newer lvcs, then run the command again. Or a node doesn't speak a protocol the request needs (not_supported, discussion:owner/400): install a newer lvcs on that node's machine.
migrate
An LVCS-owned file under .lvcs/ has an older format, or none (written before format headers): run agentflare migrate in the project root with no daemon running, then run the command again.
none
Nothing the caller can do changes the answer.
Notification kinds
Kinds of notification: a notification's kind. A notification names who sent it, where, and when, never what they wrote; read its content with notifications.read.
event
An event addressed to you (discussion:owner/515): a plugin's (<plugin>.<name>, such as messaging.mention), or core's. Its metadata names the event's kind, address, and fold key; its content is the event's body, read with notifications.read.
announce
Another peer's write notification: it is about to change, or has just changed, a range of a file (discussion:owner/513).
stale_save
A save of yours to a tree file was applied on an older version of the file than the one it replaced, so others' changes between them may be merged into it.
refused_write
A write of yours to a tree file was refused and not shared: it names the path, and its content gives the refusal's reason and how to recover. A cause that clears by itself (a grant arriving) sends the save again with no one asking; a secret-scan false positive is saved with agentflare add --force <path> (discussion:owner/513).
write_held
The tree could not write a file you author because another program held it open or denied access to it (Windows), and stopped trying after its deadline: the file on disk is older than its document. Close the file in the program holding it; the next render writes it.
executable_cleared
A save of yours through a tree cleared the executable bit of a file that had it (discussion:owner/366), as a tool that writes a new file and renames it over the old one does unless it copies the mode. The bit is part of the file, so every node and every run now has it cleared. If the file should stay executable, chmod +x it.
action_failed
An action failed at a frontier, and you changed a file it reads since the frontier where it last passed: one per action and failing streak. It names the action, both frontiers, the lines you changed, and the window's other authors; its content is the failing output's tail. Fix the change, then the next passing frontier sends an action_succeeded.
action_succeeded
An action that failed after your change passes again at a later frontier, which ends its failing streak.
derived_superseded
Your version of a derived (generated) file is not the one shown: another peer's version of it was chosen, so yours is hidden.
path_collision
A file of yours lost its name to another with the same path, exactly or by case and Unicode normalization (history row 458): two were created or moved there at once, and the one with the smaller id kept the name. Yours now shows as <stem>~<tag><ext> in the same directory; rename it to settle the collision.
file_restored
A file you edited was removed, with a directory above it, by another peer at the same time (history row 458): the edit kept it, and it is back at its last path, its directories with it. Both authors get one; remove it again if it should go.
derivation_failed
A generator failed, or runners disagreed on its output, on inputs you changed since its last counted generation: one per derivation, a newer one replacing it. Its content names the generated file to run agentflare explain on, which shows the generator and the failure; fix the inputs.
incompatible_node
A node of the project runs a release whose wire major version differs from this daemon's, or speaks no sync protocol this daemon does, so nothing syncs with it: one per node and daemon run. Its content names the node, both versions, and who upgrades: you (upgrade) when the node's is newer, else the node's owner (ask). agentflare status lists the node too.
verdict_disputed
Another node refused changes of a peer that this daemon's own checks admit, judging by the same rules and the same grants (discussion:owner/549): since the checks are deterministic, one of the two nodes has a bug. This daemon keeps the changes. To the daemon's default peer, once per document, refusing node, peer, and counter in a daemon run; its content names the document, the signer, the node, both verdicts, and the rules version. agentflare status shows a disputed line while it is unread.
protected_held
A change to a protected path by a peer who doesn't hold Approve on it is held, while the approved lvcs.toml declares no change action (discussion:owner/314): to the owner and each Approve holder this daemon holds, once per path and held heads. It names the path; its content names who wrote it. Your own edit of the path built on the held change approves it, so read the held change first (read at main shows it).
plugin_upgrade
A bundled plugin's manifest on disk (after agentflare update) differs from its record and asks more than it holds, or its upgrade was refused (discussion:owner/535): to the owner, once per plugin and manifest. The plugin keeps running as recorded; its content says what it asks, and next is agentflare plugin upgrade <name>.
Derived rules
Which rule made a file derived or not (discussion:owner/172 and discussion:owner/179), in the order the classifier tries them; the first that applies wins. A vocabulary for agentflare status and agentflare explain <path>, never a telemetry attribute value.
lvcs_toml
A the generator's writes pattern in lvcs.toml at its approved heads decided, tried first: a pattern makes the file derived, and a ! pattern makes it not derived.
pattern
The path matches DERIVED_PATTERNS, tried after every lvcs.toml rule.
marker
One of DERIVED_MARKERS is in the file's header, tried last.
none
No rule makes the file derived, or the path is in NEVER_DERIVED, which is checked before every other rule.