Troubleshooting & error codes
One article per failure people actually report. Each names what to redact before sharing anything.
- How to read a TOVIO error codeThe TVO-AREA-NNN shape, the exit-code classes, and where the remediation lives.
- Collect diagnostics safelyWhat to gather, and what to strip before sharing it anywhere.
- tovio: command not found, or the wrong version runsPATH problems, duplicate installs, and the version flag.
- I cannot read a protected fileTVO-PERM-001 — the most reported failure, and its diagnosis.
- My change has uncommitted work I did not expectAuto-snapshot, and what usually causes the surprise.
- Token expired or out of scopeThe TVO-TOKEN family, including mid-session expiry and what cannot be renewed.
- Key problemsThe TVO-KEY family: missing, expired, unwrap failures, and recovery.
- Cannot reach a remoteTVO-NET and TVO-SYNC: TLS, pinned identities, proxies, admission.
- Sync will not converge or materializeTVO-SYNC, including a teammate's change not appearing.
- Lock denied or stuckThe TVO-LOCK family.
- Object store corruptionTVO-STORE, fsck, and what a hash mismatch means.
- Import or bridge failedThe TVO-MIG family.
- A plugin refused to loadReading the TVO-PLUGIN codes.
- MCP client will not connectTVO-MCP: transport, bearer secret, and why remote access needs a proxy.
- Conflict surface errorsWhen resolve itself refuses.
- TOVIO feels slowLarge repositories, and the things actually worth tuning.
- Known issues in the current releaseLimitations worth knowing before you hit them.
- Push refused: the remote lane has divergedTVO-SYNC-006 — why a push-only sync is the one thing that will not auto-reconcile.
- A required plugin blocked your commit or landTVO-PLUGIN-009 and TVO-PLUGIN-010 — an enforcing gate doing its job.
- Recovering after losing your identity keyTVO-KEY-006 and the recovery phrase generated at init.
- A partial clone cannot fetch an objectTVO-SYNC-005 — promisor backfill, and why it is not corruption.