
How to fix Anchor, Solana CLI (Agave) and platform-tools version mismatches
Short answer
Line up five things: the Anchor CLI, the anchor-lang crate, the Solana CLI (Agave), the platform-tools that cargo build-sbf uses, and what Cargo.lock actually resolved. Check each version, pin Anchor and Solana in Anchor.toml under [toolchain], and switch with avm and the Anza installer. oms toolchain check --project <path> compares a project with pinned versions without running any of its code.
- Who it’s for
- Solana developers whose build fails after an upgrade, a fresh clone, or a manifest change an AI agent made without checking the installed versions.
- Last checked
- , against Oh My Sol 0.1.0
Why do Solana toolchain versions drift?
A Solana program build depends on several tools that are versioned separately: the Anchor CLI, the anchor-lang crate your program imports, the Solana CLI (the Agave client from Anza), the platform-tools compiler that cargo build-sbf uses, and whatever versions Cargo.lock resolved for every dependency. A fresh clone, a global upgrade or a dependency bump can move one without the others.
An AI agent that edits a manifest without checking the installed tools can add one more mismatch, so tell it the versions your project uses. A common symptom of drift is anchor build failing with “lock file version 4 requires -Znext-lockfile-bump”, which comes from a lock file newer than the compiler reading it.
How do I see which versions I actually have?
anchor --version # Anchor CLI
solana --version # Solana CLI, client: Agave
cargo build-sbf --version # platform-tools and rustc used for the program
avm list # Anchor versions avm can install or switch to
cargo tree -d # crates resolved at more than one versionThen open the project files: [toolchain] in Anchor.toml, the anchor-lang version in programs/*/Cargo.toml, the Anchor client version in package.json, and Cargo.lock, which records what was really resolved.
How do I fix a mismatch by hand?
- Pin the project. In
Anchor.toml:[toolchain] anchor_version = "1.2.2" # anchor-cli version to use (requires avm) solana_version = "4.4.1" # applies to all Solana tools - Install and select Anchor:
avm install 1.2.2, thenavm use 1.2.2. Keepanchor-langin your program’sCargo.tomlon the same version. - Install the Solana CLI version you pinned with the Anza installer and a release tag:
sh -c "$(curl -sSfL https://release.anza.xyz/<tag>/install)". Release tags are on the Agave releases page. - Choose platform-tools explicitly if the default does not match:
cargo build-sbf --tools-version v1.58, with--force-tools-installto replace an existing install. - Resolve duplicates that
cargo tree -dshows, for example withcargo update -p <crate> --precise <version>, then rebuild withanchor build.
The version numbers above are the ones Oh My Sol (OMS) pins. Use the versions your project targets. Sources: Anchor installation, Anchor.toml reference.
How does oms toolchain check find drift?
oms toolchain check --project <path>
oms toolchain fix --project <path> # prints proposed edits only
oms toolchain fix --project <path> --apply --verify # writes them in a linked Git worktreeoms toolchain check reads Anchor.toml, Cargo.toml, Cargo.lock, package.json, config and config.toml, plus .ts, .tsx, .js, .mjs and .rs files. It does not run your code. It compares what it finds with the pinned toolchain:
| Pinned in Oh My Sol 0.1.0 | Version |
|---|---|
| Anchor | 1.2.2 |
| Solana and Agave | 4.4.1 |
| platform-tools | 1.58 |
| SBPF arch | v3 |
Each finding has a rule id (anchor, pins, crates, duplicates, client, transaction, arch or advisory) and a source URL. The advisory rule flags Anchor 1.0.0 and 1.0.1, but only when the lock file confirms that version.
Inside an OMS session the same check runs for the model: a summary of the report goes into its system prompt as untrusted project data, and it can call a toolchain_check tool for the full report, so it starts from your real versions.
What does the check need?
- The check compares against the pinned set above. If your project targets other versions on purpose, read the findings as a list of differences.
- TOML parsing needs Python 3.11 or newer (
python3 --version). --applyrefuses to run outside a linked Git worktree. Create one and run it again.- Reading stops at depth 12, 2,000 files, 2 MB per file and 16 MB in total. Narrow
--projectto the package you care about. - It skips symlinks and the
.git,.oms,node_modules,target,vendorand.oms-cargofolders.
Frequently asked questions
How do I check which Anchor, Solana CLI and platform-tools versions I am using?
Run anchor --version for the Anchor CLI, solana --version for the Solana CLI (the client is Agave), and cargo build-sbf --version, which prints the platform-tools and rustc versions it builds with. Then compare them with the anchor-lang version in your program’s Cargo.toml and the versions locked in Cargo.lock.
How do I pin the Anchor and Solana versions for a project?
Add a [toolchain] section to Anchor.toml with anchor_version (which requires avm) and solana_version (which applies to all Solana tools). Install the Anchor version with avm install <version> and select it with avm use <version>.
How do I install a specific Solana CLI (Agave) version?
Run the Anza installer with a release tag instead of stable: sh -c "$(curl -sSfL https://release.anza.xyz/<tag>/install)". The available versions are listed on the Agave GitHub releases page. agave-install update moves you to the latest release.
How do I build with a specific platform-tools version?
Pass --tools-version to cargo build-sbf, for example cargo build-sbf --tools-version v1.58. Add --force-tools-install to replace an existing install.
Does oms toolchain check run my code?
No. It only reads Anchor.toml, Cargo.toml, Cargo.lock, package.json, config files and source files, compares them with the pinned versions, and reports findings. Nothing in the project is executed, so it is safe to run on code you have not reviewed yet.
Will oms toolchain fix change my files?
Not by default. oms toolchain fix only prints proposed edits, and any commands are proposed, not run. With --apply it writes the edits, but only inside a linked Git worktree and after checking that the files still match what it read. Add --verify to verify afterwards.
Try it on your own program
Oh My Sol 0.1.0 runs on macOS and Linux, and on Windows through WSL 2. You need Node 22.19.0 or newer and Git. You bring your own model access: an API key, a ChatGPT subscription or a Claude subscription.
npx @barestate/oms doctor --install
npx @barestate/oms