PluginsEarly
Errors
Every error code a plugin can meet, and where it comes from.
From the plugin interface of gr 0.2.16 (API 0.1, 0.2, 0.3). gr plugin api errors prints it on your machine.
These codes name what went wrong in a failed call, in gr plugin check and gr plugin status, and in a plugin's log. "Raised by" says which part of Graphide refuses: check is gr plugin check, host the process the plugin runs in, tests the test host.
| Code | Means | Raised by |
|---|---|---|
manifest.parse | plugin.toml does not parse | check |
manifest.name | the name's pattern, or a reserved or taken name | check |
manifest.link | a symbolic link, an outside hard link or a special file in the folder | check |
manifest.size | the folder over 2 MiB or 200 files; a language pack's, a plugin with [[languages]], over pack_bytes or pack_files | check |
manifest.version | the version is not semver | check |
manifest.api | an api the host does not serve | check |
manifest.description | the description is missing or over 300 characters | check |
manifest.main | the main file is missing or its extension is not .ts, .tsx, .js or .jsx | check |
manifest.unknown_key | a key the schema does not have; kept (a warning) | check |
contribution.namespace | an id or command not starting with <name>. | check |
contribution.duplicate | two contributions with one id | check |
contribution.value | a contribution's field missing, or holding a value the schema does not have: a dock, an icon, a side, a static tree file | check |
capability.unknown | a capability or scope the schema does not have | check |
capability.scope | a scope that does not parse, or a call outside its scope | check, daemon |
keys.notation | keys that are not Vim notation | check |
keys.target | a key bound to a command the plugin does not declare | check |
keys.reserved | one unmodified printable key in normal or visual mode, or any unmodified key in insert mode | check |
keys.taken | a default the preset, the defaults or another plugin binds; left unbound (a warning) | check, app |
settings.kind | an unknown kind, or a default of the wrong kind | check |
limits.over_cap | a limit over its cap | check |
event.unknown | an event name the schema does not have | check |
api.removed | a name that was in 0.1 before it shipped and is gone: the message names what to write instead (removed) | check, host |
event.undeclared | the script handles an event the manifest does not declare | check |
eager.reason | eager = true without eager_reason | check |
handler.none | a declared command, panel or picker with no handler (a warning; a panel may be static) | check, host |
fixtures.shape | a world that is not a world's shape: fixtures/world.json, a render's state, or what a test gave t.fixtures | check |
script.syntax | the script does not compile; file, line and column | host |
script.throw | a handler threw | host |
script.timeout | a handler ran past its hard budget | host |
script.stack | the stack overflowed | host |
script.size | a built-in asked for more than 64 MiB | host |
script.global | the script uses a global a plugin does not have (fetch, process, Buffer, XMLHttpRequest, eval, Function); a warning | check |
result.shape | a handler returned the wrong shape; the message carries a path into the value | host, daemon, app |
result.not_json | a value that is not JSON crossed the boundary | host |
result.too_large | an answer would encode past 8 MiB, or (0.2) a tool's answer past tool_answer_bytes | host, daemon |
state.full | a $.state write past 4 MiB an instance, or a $.store write past 1 MiB a plugin | host |
timers.over | a timer past the 64 a plugin may have at once | host |
host.protocol | the host and the daemon speak different protocols, or a line broke the protocol | host, daemon |
host.restarted | the plugin's host restarted during the event | daemon |
plugin.off | the plugin is switched off for the session: past its memory cap, its circuit breaker tripped, or a host of another protocol | daemon |
tree.bound | a tree over a bound; the last good tree stays | daemon, app |
contribution.foreign | a view, segment, set or picker the plugin does not declare | daemon |
command.refused | a command outside the schema, an action off the allowlist, or a path outside the root | daemon, app |
capability.undeclared | a method whose capability the manifest does not declare; or (0.2) [[tools]] in a manifest whose [allow] agents does not hold "tools"; or (0.2, a warning) [[completions]] in a manifest whose [allow] fs does not hold "read:workspace", which the editor then asks nothing | check, daemon |
capability.denied | a method whose capability is declared and not granted | daemon |
calls.over | an event made more than 1,000 calls | host |
fs.refused | a path outside the root, or in the daemon's folders or a secret folder | daemon |
exec.unsandboxed | no sandbox on this machine, so exec is refused | daemon |
exec.root | the root is the home folder or holds the daemon's configuration | daemon |
exec.killed | a program stopped at its 30 s or its 1 GiB | daemon |
net.refused | plain HTTP, Graphide's own hosts, private or metadata addresses | daemon |
approve.stale | the hash approved is not the current one | daemon |
approve.from_agent | the caller descends from an agent, or could not be checked | daemon |
approve.capability | a grant the manifest does not declare | daemon |
api.newer | the plugin uses a name newer than the api its manifest says; set api to that version | check |
agents.rate | an agents.send past the 20 a minute a plugin may make, or an agents.start past the agents it may start in ten minutes (agent_starts); nothing was sent or started | host, daemon |
agents.bound | a message, a prompt or attached text over agent_text_bytes, or a name over 80 characters; nothing was sent | host, daemon, app |
agents.unreachable | an agents.send to an agent that is not running, is a terminal, or shows a dialog its person must answer; or an agents.start the daemon could not make (its harness signed out, the workspace starting agents faster than a person would); nothing was sent or started, and the message says why | daemon |
net.secret_header | a fetch to the host a secret setting is bound to sets that secret's header itself: leave it out, and the daemon puts the secret there once the person has entered it | daemon |
image.refused | an image a view names that the editor cannot draw: no file of that path in the folder that runs, not a PNG, over 4 MiB or over 4096 by 4096 pixels; drawn as its alt in a box, and said once in the plugin's log and in gr plugin status | app |
terminals.over | a terminal.open past the 4 a plugin may have open | daemon |
graph.none | a graph.* call for a root that has no graph: plugins run in any folder a window has open, and a folder Graphide has not graphed has none. To graph a folder, run gr init in that folder; it initializes .graphide/graph.db and builds the project graph. | daemon |
docs.undeclared | the plugin uses $.docs or a document event without a [documents] table in plugin.toml. A bare [documents] reads every document; languages = ["go", "markdown"] (lower case, as the highlighter names them) narrows it to those, and there is no wildcard | check, daemon |
menu.place | a [[menus]] place that is not one of card, map, box, atlas, agent, mark, agents, composer, code, terminal, node, pane and tab | check |
menu.command | a [[menus]] command that is not one of the plugin's own: a command, a panel, a status segment or a picker it declares | check |
tool.input | a tool call's input does not fit the tool's [tools.input]: not an object, a required property missing, one it does not take, or a value of another type; the message names the path ($.path, $.kinds[2]); the handler never ran | daemon, host |
tool.timeout | a tool's handler did not answer within the 30 s an agent's call waits (tool_wait_ms); it may still be running, and its answer is dropped | daemon |
tool.unknown | a tool call names a tool no plugin of the root offers now: not installed, not approved, switched off, or without agents:tools granted | daemon |
mcp.unavailable | a tool of a plugin's MCP server was called and the server is not there to answer: its start failed (the message says how, and its standard error is in the plugin's log), it exited during the call, or it failed five times in ten minutes and is off for the session | daemon |
mcp.error | a plugin's MCP server answered a tool call with an error; the message is what it said, cleaned of control characters | daemon |
mention.prefix | a [[mentions]] prefix that is not 1 to 16 lowercase letters, digits and hyphens beginning with a letter, or that two of the manifest's sources share | check |
mention.entry | an entry of a mention's answer left out, the others kept: no key or label, a key twice, an attach that is not one of node, file, agent or text, a file outside the root, a node the graph does not hold, an agent not in the roster, or text without agents:write or over agent_text_bytes. Said in the plugin's log with the entry's key and why; never attached | daemon, host |
decorations.bound | a set of marks over a bound (decoration_marks, decoration_bytes, decorations_root_marks) is refused, naming the bound; the set held before stays | host, daemon, app |
decorations.documents | the manifest declares [[decorations]] without a [documents] table: marks are kept true against the documents the editor mirrors | check |
query.language | a [[queries]] names a language the editor has no grammar for. A query plugin is data: [[queries]] id = "<plugin>.<name>", language (bash, c, cpp, css, diff, go, html, javascript, json, lua, markdown, nix, python, rust, sql, toml, tsx, typescript or yaml), file (a .scm file in the plugin's folder, at most 64 KiB), and [queries.captures] naming each capture's mark: { kind = "underline", style = "wavy", tone = "warning", detail = "a TODO" }, kind one of sign (text, at most 2 characters, or icon), underline (style), tint (tone, lines) or eol (text). The editor runs the query on each file of that language you have open, off the window's thread with its colours, and marks every capture's node; it needs approval like any plugin and asks for no capability. Example: ((comment) @todo (#match? @todo "TODO")) with todo = { kind = "underline", tone = "warning" } | check |
query.file | a [[queries]] file is not a .scm file inside the plugin's folder, the folder does not hold it, or it is over query_bytes or not UTF-8 | check |
query.syntax | a query's S-expression is not balanced: a parenthesis or bracket left open or closed twice, or a string left open; the message says the line and column in the .scm file | check |
query.capture | a capture [queries.captures] names is not captured in the query's file, or the file captures a name the table does not name; a capture whose name starts with _ (@_name, for a predicate) needs no mark | check |
query.compile | the editor could not compile a query for its language's grammar: a node type or field the grammar lacks, or a predicate other than #eq?, #match? and #any-of?, with their not- and any- forms (#set! is read and does nothing); said on the message line, in :plugin status and in gr plugin status, and the plugin's other queries still run | app |
when.parse | a when clause does not parse: the column says where (contract C4: && || ! ( ) == != < <= > >= in =~, at most 256 characters, 8 deep) | check, config |
when.key | a when clause asks a key that is neither a context key nor a plugin's own (<plugin>.<name>); it has no value, so it is false | check |
graph.derived | An extracted identity cannot be changed by a plugin; the authored layer's reason is preserved. Descriptions and tags are annotations and remain writable. | daemon, tests |
graph.rate | More than 10 graph write calls in a second for this plugin; nothing was written by this call. | daemon, tests |
graph.bound | More than 1,000 ids in a graph write call; nothing was written. | host, daemon, tests |
lsp.no_server | no language server serves the root or the file: the root is not trusted, [lsp] switched it off, or no server for the file's language was found | daemon |
lsp.unsupported | the file's language server does not answer what was asked | daemon |
lsp.failed | the language server did not answer: it failed, took too long, or the file changed twice while it was asked; the message says which | daemon |
language.id | a [[languages]] has no id, its id is not a language's (lower-case letters, digits and _ . + # -, at most 40), or the plugin declares the language twice | check |
language.file | a language's grammar is not a .wasm file inside the plugin's folder, or a query is not a .scm file inside it; the folder does not hold it; or a query is over language_query_bytes or not UTF-8 | check |
language.grammar | a language's grammar is not a WebAssembly module, or does not export tree_sitter_<name>, where <name> is its file's name without .wasm and a leading tree-sitter-, each - and . an _; or the language has queries and no grammar to run them on. Build a grammar with tree-sitter build --wasm, or with an emscripten-free clang to wasm32 as Graphide's own tests do | check |
language.linked | a warning: the editor links a grammar for the language, which colours its files, so the pack's grammar and queries go unused; its server, comments and brackets still apply | check |
language.load | the editor could not load a language's grammar (not a tree-sitter grammar it can run, or one built for a newer tree-sitter) or compile one of its queries for it (a node type or field the grammar lacks); said on the message line, in :plugin status and in gr plugin status, and the language's files open uncoloured | app |
setup.unavailable | the daemon could not answer a setup call: setup.layer for a root whose graph is not open, or a setup.read it could not make; the message says why | daemon |
These docs describe Graphide 0.2.16, the latest release. Something wrong or missing? Tell us onDiscord or at hello@graphide.com.