Skip to main content
Plugins

A plugin will not load or run

Reading the TVO-PLUGIN codes, and plugin doctor.

Written By Dustin

Last updated About 1 month ago

tovio plugin doctor
tovio plugin list
tovio plugin bindings
tovio explain plugin

Start with doctor. It checks every manifest, every artifact's integrity, and every binding without executing anything, and exits non-zero if any of them is broken.

The local codes

CodeWhat it means
001Manifest failed validation — a bad id, version, or type, an event it cannot run, a contradictory capability request, an unknown --grant token, or a manifest file that is missing, unreadable, or not valid TOML.
002Not installed in this repository's store, or an install source that is neither a local path nor a permitted HTTPS package URL.
003The package did not establish its integrity and trust state — a hash mismatch, an invalid signature, or an untrusted or revoked publisher. Fail-closed, no override.
004Unsupported event — a bind or run for an event the manifest does not declare, or an event name outside the vocabulary entirely.
005Capability denied by the manifest-and-binding intersection.
006Sandbox failure — a corrupt or non-WASM artifact, an ungranted host import, a non-zero exit, a manifest-only package with nothing to execute, a run with no binding for that event, or a build without plugins-wasm.
007Terminated on the fuel budget, the wall-clock deadline, or the memory ceiling.
008Output failed schema validation, or claimed a different plugin id or event than the one that ran. Coerced to error, never to a pass.
009A required enforcing plugin ran and returned fail, so the commit or land was blocked before it took effect.
010An enforcing plugin could not produce a passing verdict — it errored, skipped, reported unsupported, is not installed, or this binary has no sandbox. Blocks when the binding is required, and also when the plugin errored on an operation touching protected content, even if the binding was not marked required. Fail-closed.
011Protected plaintext requested and denied at execution preflight.
012Network access requested and denied at execution preflight.
013Two different things. Either --grant read_protected_plaintext was refused at bind or hook authoring, and nothing was written — or a required enforcing plugin on a post-event failed after the operation was already durable. The message tells you which.

009 and 010 are the two you are most likely to meet, because they are what a blocked tovio commit or tovio land reports. Both name which plugin blocked, which binding required it, what failed, that the result was local rather than CI-side or Forge-side, and whether an override is possible.

The post-event form of 013 is different in kind: the snapshot, land, or conflict record is already durable, so nothing was prevented. TOVIO records the failure in the signed audit chain and exits non-zero so CI observes it, but reverting or re-doing the operation is your decision, not something the plugin can force.

The common causes, in order

  1. Built without plugin execution. Not an error in itself — your binary lacks the plugins-wasm feature. But a required enforcing binding in a lean build always blocks with 010, because an un-runnable required gate is not allowed to pass silently. Rebuild with the feature.
  2. Not bound. plugin run executes under a binding, so mode and grants are well defined. With none, it refuses. Use plugin test <path> --event <event> to run a package without installing or binding it.
  3. Missing --event. Both run and test require it.
  4. A dangling binding. The plugin was removed, or reinstalled under a different id. doctor names it.
  5. An ungranted import. The guest reached for network, filesystem, or environment. Check what the manifest requests against what the binding grants.

On a Forge

014 — an enforcing binding refused by organisation allow and deny policy. 015 — a required plugin with no attested passing result for the current revision. 016 — a hosted plugin registration refused at upload.

Before you share output

Plugin findings can quote file paths and code. Redact paths, hostnames, identity DIDs, and anything a finding excerpted from a file before pasting output into a support conversation. Secret-scan findings carry redacted previews rather than raw values, but the surrounding output is ordinary repository content.

Was this helpful?

Still need help? Ask the team