When the build fails

Almost every failed TOVIO build is one of a small number of things. Work down this list before assuming something exotic.

Windows: a wall of linker errors

You are building under the GNU toolchain. The TLS transport (rustls over aws-lc-rs, pulled in through tovio-proto's transport feature) cannot link there, and the errors name symbols that look unrelated to TLS.

Install the Visual Studio Build Tools with the "Desktop development with C++" workload, then make MSVC the active target:

rustup default stable-x86_64-pc-windows-msvc

If you genuinely only want to try local version control with no networking, the GNU toolchain still builds the offline core on a best-effort basis — tovio-core, tovio-cli, tovio-keystore and tovio-proto with default features. It is not the supported configuration, and clone, sync, push, pull and serve are not in it.

Linux: a build script fails compiling C

You are missing a C compiler. The Linux keychain backend vendors libdbus and compiles it from bundled source, so cc has to exist. Install build-essential or your distribution's equivalent.

What you do not need is libdbus-1-dev or libsecret development headers. Vendoring exists precisely so that prerequisite is gone; a guide that tells you to install them predates that change.

Cargo refuses on rust-version

Your compiler is older than the workspace minimum of 1.75. rustup update stable is the fix. The repository pins the stable channel through rust-toolchain.toml, not a specific version, so rustup will not upgrade you on its own.

It builds, but commit fails with TVO-CORE-000

On Windows, a deep repository root can push the object store's nested paths past the classic Windows path limit, and the symptom is characteristic: tovio init succeeds, then tovio commit fails with TVO-CORE-000 and i/o error: The system cannot find the path specified. (os error 3). The failure therefore appears one command after its cause, and the root directory itself can look perfectly reasonable.

Move the repository somewhere short. Do not assume enabling the Windows long-path setting alone will lift it.

TVO-CORE-000 is the generic engine fallback, exit class 1. Reaching it anywhere else is itself worth reporting — it means a specific error code is missing for whatever you hit.

Narrowing an unclear failure

cargo build -p tovio-core

cargo build -p tovio-cli

Building the pure core first separates "the engine does not compile" from "an edge dependency does not compile". tovio-core performs no I/O and pulls in none of the platform integrations, so if it builds and the CLI does not, the problem is in the edge layer — the keychain backend, the TLS transport, or the WASM plugin sandbox.

To rule out the plugin sandbox and the parser trees entirely, build lean:

cargo build -p tovio-cli --no-default-features

That drops semantic, secrets and line-ops. It is a diagnostic, not a destination — secrets is the default-on secret scan, so do not ship yourself a binary without it by accident.

Stale artifacts after a toolchain change

If you changed Rust versions or switched target triples mid-stream, clear the tree once:

cargo clean

cargo build --release -p tovio-cli

This is genuinely a last resort — a full rebuild of the workspace is slow, and cargo clean fixes far fewer problems than folklore suggests.