When a sync is refused

Sync failures split into three kinds, and telling them apart is most of the diagnosis: the network did not work, the remote is not who you pinned, or the operation was deliberately declined. The third kind is the one people misread — it means the transfer worked and TOVIO chose not to proceed.

Every code below has its own page at https://tovio.dev/errors/<CODE>, and the error catalog on the documentation site is the canonical text. This article is the triage map, not a copy of it.

The network did not work

TVO-SYNC-001 (unreachable), TVO-SYNC-002 (wire-protocol version mismatch), and TVO-SYNC-003 (the connection, handshake, or transfer did not complete).

These are the retryable ones. Your commits are safe and unchanged — TOVIO is offline-first, so keep working and sync later. If a valid address keeps producing TVO-SYNC-003, suspect the pinned certificate rather than the network.

The remote is not who you pinned

TVO-SYNC-004 (the relay's serving identity changed), TVO-SYNC-007 (the repository owner identity changed), and TVO-SYNC-008 (the served policy manifest is unattested, or its version would move policy backwards).

All three fail closed, and none advances a ref. Do not work around them. The first two mean the other end proved itself and is not what you trusted before — confirm a deliberate re-key with the operator before re-pinning, because the alternative explanation is interception. The third is why an owner signature never expiring is safe: version ordering is what stops an old signed manifest being replayed to weaken policy, and the fix is for the owner to publish a newer one.

The operation was declined

TVO-SYNC-006 means a push-only sync would have orphaned a diverged remote tip. Nothing was uploaded. Run a full tovio sync to reconcile on-lane; the push is then a fast-forward.

TVO-SYNC-005 means a partial clone needed an object the promisor could not supply. See the article on filling in a partial clone.

TVO-CONFLICT-004 means the pull brought in a change you depend on that still holds unresolved conflicts, so the sync stopped before pushing. Resolve it, or re-run with --isolate to build against the last known clean version.

Refused at the door

These come from a Forge, before or instead of a transfer, and none of them is a transport problem.

TVO-NET-001 — the connection's source address is not permitted by the CIDR policy, evaluated at admission before the connection ACL and before authentication. This is a Forge feature; tovio serve has no such policy, so it never produces this.

TVO-FORGE-004 — the connection ACL denied you. Worth knowing that the same gate covers the Forge's metadata reads, so an ACL-enabled Forge will also refuse tovio forge lock list and friends to a non-member.

TVO-FORGE-080 — a direct push touched a change-controlled path. Open a proposal instead.

Before you share a failure

Sync errors are written to be safe to paste: they name codes, addresses, and workflow conditions, never file contents, path plaintext, or key material. Still read any terminal transcript you attach for repository paths, hostnames, and identifiers you would rather not publish, and never include the contents of .tovio/.

What is never lost

Every failure above leaves your local history untouched. Nothing in this list is a reason to re-clone, and none of them advances a ref on either side.