Skip to content

Troubleshooting

When something doesn't go the way you expected, TOVIO tries to tell you exactly what happened and what to do next --- every error it prints has a code (TVO-AREA-NNN) and a runnable next step. This page collects the situations people hit most, framed the same way the CLI frames them: what you're seeing, why it happens, and what to do next.

Every error has a code and a fix

If you see a TVO-* code, the full catalog entry --- with its remediation --- is in the error reference. The CLI prints the most likely fix right in the message; you can usually copy-paste it.

Current implementation boundary

The permission and agent control planes are implemented. Entries below distinguish commands that run today from remaining gaps; the roadmap and repository implementation ledger govern status.

Everyday operations

"command not found: tovio" or the wrong version runs

What happened. Your shell can't find the tovio binary, or it's running an old copy.

Why. The binary isn't on your PATH, or a stale one earlier in PATH shadows the new one.

What to do next.

  • Confirm what's resolved and where: tovio --version and which tovio (or where.exe tovio on Windows PowerShell).
  • If nothing resolves, re-check the install step in getting started and make sure the install directory is on your PATH.
  • If an old version runs, remove or reorder the stale copy so the new directory comes first.

My change has uncommitted work I didn't expect

What happened. tovio status shows modifications you don't remember making.

Why. There is no staging area --- your working copy is continuously snapshotted into the current change. Every edit on disk is already part of the change-in-progress; nothing waits to be add-ed.

What to do next.

  • Run tovio status to see exactly what's in the current change, then tovio diff to inspect it.
  • If the changes are wanted, tovio commit -m "..." finalizes them.
  • If they aren't, tovio undo can reverse the retained local operation that introduced them; tovio redo puts that operation back.

I ran the wrong command and want it back the way it was

What happened. A commit, lane delete, switch, or rebase did something you didn't intend.

Why. This is exactly what the local operation log exists for: supported recorded mutations are reversible.

What to do next.

  • Run tovio undo. It states what it undid and how to tovio redo.
  • Undo again to step further back through retained reversible entries; the op-log covers more than commits.
  • Check the boundary before relying on it: remote observations, external service effects, authenticated obliteration, and entries beyond local retention are not recalled.

git push / git pull / git add "didn't work"

What happened. You typed a Git command out of habit.

Why. Those are Git verbs. TOVIO answers them instead of rejecting them: some do the equivalent native thing, the rest print a gentle note naming the native command. Nothing scolds you.

What to do next.

  • tovio push and tovio pull are real one-directional relay commands, not aliases. Run bare, each prints the explicit form (tovio push <relay> <repo> --cert <file>, or an https:// Forge with no cert) and reminds you that TOVIO unifies git push/git pull as tovio sync. That hint is a git-compat note, so if you have turned those off (tovio config set compat.git.notes off) a bare tovio push prints nothing and exits 0 --- it did not transfer anything.
  • tovio checkout does what tovio switch does; tovio branch (and tovio br) do what tovio lane does.
  • tovio add and tovio stash are notices --- there is no staging area, and your work is already a tracked change. tovio reset points you at tovio undo.
  • Follow the gentle note toward the native command --- over time it builds the new habit. The Git mapping table lines the two models up side by side.

Conflicts & syncing

"diverged history" --- where is it?

What happened. You expected the Git "your branch and origin have diverged" error after working offline and syncing. It never appeared.

Why. When two replicas move the same unprotected lane independently, a sync reconciles them on the lane into a two-parent commit — both tips become parents, so neither is stranded off-lane, and no force-push is ever needed. There is no diverged-history state to recover from. (An HLC-keyed CRDT register propagates that reconciliation pointer underneath; it is the mechanism, not the resolution.)

What to do next.

  • Nothing, if the two sides merged cleanly — the sync output tells you it reconciled the lane automatically.
  • If the underlying content genuinely conflicts, the reconciliation commit carries conflict objects on the lane (next entry) — still not an error; you resolve them when ready.

A merge or land reported conflicts --- is my work broken?

What happened. A land, merge, or sync finished and told you conflicts were stored.

Why. Conflicts are first-class objects, not a failure state. The operation succeeded --- the conflict is recorded as data so your work keeps moving, and you resolve it when you're ready. A stored conflict is marked with a success glyph, never an error glyph.

What to do next.

  • Keep working --- nothing is blocked. Resolve when convenient.
  • List what's outstanding with tovio conflicts --- every open conflict in the current change and how to resolve each. It exits 0, because a conflict is data rather than a failure.
  • Check whether the current lane is clean and landable with tovio health, or assess one change by id with tovio change health <change-id>.

tovio sync won't materialize a teammate's change into my tree

What happened. A sync refused to pull a dependency into your working tree (TVO-CONFLICT-004).

Why. That change still has unresolved conflicts. TOVIO won't hand you a broken build by materializing a conflicted dependency by default.

What to do next.

  • Wait for the upstream conflict to resolve, then sync again --- the gate clears automatically.
  • If you need to build now against the last-known-clean version, use tovio sync --isolate; it auto-updates once the upstream conflict resolves.
  • tovio change notify <change-id> records a durable reminder to be told when that change reaches a watched state. It is local and never synced, so it does not message the author; delivery is the Forge event feed's job, which tovio change watch <change-id> --remote <host:port> polls. Without --remote there is no live event source wired, and watch fails closed rather than idling.

(Dependency-materialization gating, isolation pins, and auto-refresh are implemented.)

Permissions, keys & encryption

"Cannot read <path>" on a protected file (TVO-PERM-001)

What happened. A read failed on a policy-protected file --- TOVIO named the file, not a bare "permission denied."

Why. Reading that path requires an attribute your identity doesn't have (for example clearance=secrets). The error states what you have alongside what was required, so the gap is explicit. The file is genuinely ciphertext to you --- no key was ever wrapped for your identity.

What to do next.

  • Inspect the exact requirement: tovio access check <path>.
  • If you should have access, request the missing attribute from your Key Authority: tovio access request <path-glob> --attr clearance=secrets.
  • If you shouldn't, this is the system working as designed --- the math, not a server, is enforcing it.

(The cryptographic permission layer is implemented.)

I lost my key and can't decrypt my own files

What happened. Your identity key is gone, and protected objects no longer decrypt.

Why. Without your private key there is nothing to unwrap the per-recipient data keys with --- this is the same property that keeps unauthorized identities out.

What to do next.

  • If you escrowed the recovery phrase init generated, save it to a file and run tovio key recover --from <file>. That installs a fresh identity and re-wraps HEAD's protected content to it.
  • If what you have instead is a passphrase-encrypted backup from tovio key export <file> --passphrase-file <file>, then tovio key import <file> --passphrase-file <file> restores the same key rather than minting a new identity.
  • On a team repo where you have neither, a Key Authority operator can enroll your new identity --- tovio access grant --identity <identity.pub> --attr <name>=<value>. That grant is prospective: it takes effect on the next commit of a matching protected path, so already-committed content becomes readable to you as it is next sealed, not retroactively.
  • Going forward: back up the recovery phrase, and any key export file, the way you'd back up an SSH key.

(Key export/import/recovery, key status, and prospective access grant re-wrapping are implemented. Renewing your own certificate against a remote Key Authority is not.)

An attribute certificate or agent token is about to expire

What happened. Something you hold is time-bounded, and the window is closing.

Why. Attribute certificates and capability tokens both carry an expiry by design, so access is time-bounded rather than standing. Approaching expiry is a notice, not a failure --- nothing is broken yet.

What to do next.

  • List what this identity holds, with each certificate's issuer, expiry and validity: tovio key status.
  • On a repository that is its own Key Authority, tovio key renew re-issues the certificates this identity issued with a fresh window. Renewing your own certificate against a remote Key Authority is not a command yet --- ask that Key Authority's operator.
  • Agent tokens are the surface that warns you proactively: tovio status prints ⏳ agent token <id> expires in ~Nh while one is close, and an error line once one has lapsed. Re-issue with tovio agent renew <token-id>.

Agents

My agent can't read a file inside its own path scope

What happened. An agent operation failed on a file that is within the agent's path_scope.

Why. Path scope is necessary but not sufficient. If the file is protected by a clearance policy and the agent's token has secret_clearance: false, no key is ever wrapped for that agent --- regardless of path. This is deliberate: an agent reads code in scope, but never secrets it wasn't cleared for.

What to do next.

  • This is usually correct behavior --- the agent is scoped out of secrets on purpose.
  • No CLI flag lifts it. tovio agent new always issues the safe default: every policy-protected path is excluded from the token's scope, and secret_clearance is false. Point the agent at clear code, or do the protected step yourself under your own identity.
  • Inspect an issued token with tovio agent show <token-id>, or list the active agent sessions with their scope and expiry using tovio agent list.

An agent operation failed with "out of scope"

What happened. An agent tried to read or write a path outside the scope on its token.

Why. Path-scope enforcement runs before policy evaluation --- an out-of-scope access is rejected without even consulting the envelope. The token is doing exactly its job.

What to do next.

  • Check the token's scope: tovio agent show <token-id> (or tovio agent list for every active session at once).
  • If the agent legitimately needs the path, issue it a fresh token. A sub-token can only ever be equal-or-narrower than its parent, so delegation never widens scope.

An agent's token expired mid-session

What happened. Agent operations started failing; the token reached its expiry.

Why. Tokens expire by design and are never silently extended --- an expired token simply stops working.

What to do next.

  • Re-issue proactively with tovio agent renew <token-id> --expires-in 8 --- a deliberate re-issue on a fresh window, never an extension. --expires-in is in hours and defaults to 24 here too, so renewing a short-lived token without it silently widens the window to a day. tovio status is what gives you the advance warning; the MCP server does not warn, it simply starts no session once the token is invalid.
  • For a fresh session, tovio agent new <name> --model <model> --task "<what it is doing>" --expires-in 8 issues a new scoped token.

(The agent control plane is implemented across CLI, Node, and MCP.)

Still stuck?

  • Look up any TVO-* code in the error reference for the full catalog entry and remediation.
  • For "how do I do X" rather than "why did X fail," the cookbook and the guides have task-focused walkthroughs.
  • If you think you've found a bug, report it through the feedback portal at https://tovio.dev/feedback with the TVO-* code and your tovio --version output (see feedback, roadmap and updates). If it could expose a secret or bypass enforcement, treat it as a vulnerability and follow the coordinated-disclosure procedure instead.

Last reviewed September 9, 2026

Suggest an improvement to this page Not for security reports — see disclosure