Loading source
Pulling the file list, source metadata, and syntax-aware rendering for this listing.
Source from repo
Comprehensive Solana development skill covering @solana/kit v5, Anchor programs, LiteSVM testing, and security patterns.
Files
Skill
Size
Entrypoint
Format
Open file
Syntax-highlighted preview of this file as included in the skill package.
references/common-errors.md
1---2title: Common Errors & Solutions3description: Diagnose and fix common errors encountered when building on Solana, including GLIBC issues, Anchor version conflicts, and RPC errors.4---56# Common Solana Development Errors & Solutions78## GLIBC Errors910### `GLIBC_2.39 not found` / `GLIBC_2.38 not found`11```12anchor: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.39' not found (required by anchor)13```1415**Cause:** Anchor 0.31+ binaries are built on newer Linux and require GLIBC ≥2.38. Anchor 0.32+ requires ≥2.39.1617**Solutions (pick one):**181. **Upgrade OS** (best): Ubuntu 24.04+ has GLIBC 2.39192. **Build from source:**20```bash21# For Anchor 0.31.x:22cargo install --git https://github.com/solana-foundation/anchor --tag v0.31.1 anchor-cli2324# For Anchor 0.32.x:25cargo install --git https://github.com/solana-foundation/anchor --tag v0.32.1 anchor-cli26```273. **Use Docker:**28```bash29docker run -v $(pwd):/workspace -w /workspace solanafoundation/anchor:0.31.1 anchor build30```314. **Use AVM with source build:**32```bash33avm install 0.31.1 --from-source34```3536---3738## Rust / Cargo Errors3940### `anchor-cli` fails to install with Rust 1.80 (`time` crate issue)41```42error[E0635]: unknown feature `proc_macro_span_shrink`43--> .cargo/registry/src/.../time-macros-0.2.16/src/lib.rs44```4546**Cause:** Anchor 0.30.x uses a `time` crate version incompatible with Rust ≥1.80 ([anchor#3143](https://github.com/coral-xyz/anchor/pull/3143)).4748**Solutions:**491. **Use AVM** — it auto-selects `rustc 1.79.0` for Anchor < 0.31 ([anchor#3315](https://github.com/coral-xyz/anchor/pull/3315))502. **Pin Rust version:**51```bash52rustup install 1.79.053rustup default 1.79.054cargo install --git https://github.com/coral-xyz/anchor --tag v0.30.1 anchor-cli --locked55```563. **Upgrade to Anchor 0.31+** which fixes this issue5758### `unexpected_cfgs` warnings flooding build output59```60warning: unexpected `cfg` condition name: `feature`61```6263**Cause:** Newer Rust versions (1.80+) are stricter about `cfg` conditions.6465**Solution:** Add to your program's `Cargo.toml`:66```toml67[lints.rust]68unexpected_cfgs = { level = "allow" }69```70Or upgrade to Anchor 0.31+ which handles this.7172### `error[E0603]: module inner is private`73**Cause:** Version mismatch between `anchor-lang` crate and Anchor CLI.7475**Solution:** Ensure `anchor-lang` in Cargo.toml matches your `anchor --version`.7677---7879## Build Errors8081### `cargo build-sbf` not found82```83error: no such command: `build-sbf`84```8586**Cause:** Solana CLI not installed, or PATH not set.8788**Solutions:**891. Install Solana CLI: `sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"`902. Add to PATH: `export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"`913. Verify: `solana --version`9293### `cargo build-bpf` is deprecated94```95Warning: cargo-build-bpf is deprecated. Use cargo-build-sbf instead.96```9798**Cause:** As of Anchor 0.30.0, `cargo build-sbf` is the default. BPF target is deprecated in favor of SBF.99100**Solution:** This is just a warning if you're using older tooling. Anchor 0.30+ handles this automatically. If calling manually, use `cargo build-sbf`.101102### Platform tools download failure103```104Error: Failed to download platform-tools105```106or107```108error: could not compile `solana-program`109```110111**Solutions:**1121. **Clear cache and retry:**113```bash114rm -rf ~/.cache/solana/115cargo build-sbf116```1172. **Manual platform tools install:**118```bash119# Check which version you need120solana --version121# Download manually from:122# https://github.com/anza-xyz/platform-tools/releases123```1243. **Check disk space** (see "No space left" error below)125126### `anchor build` IDL generation fails127```128Error: IDL build failed129```130or131```132BPF SDK: /home/user/.local/share/solana/install/releases/2.1.7/solana-release/bin/sdk/sbf133Error: Function _ZN5anchor...134```135136**Solutions:**1371. **Ensure `idl-build` feature is enabled (required since 0.30.0):**138```toml139[features]140default = []141idl-build = ["anchor-lang/idl-build", "anchor-spl/idl-build"]142```1432. **Set ANCHOR_LOG for debugging:**144```bash145ANCHOR_LOG=1 anchor build146```1473. **Skip IDL generation:**148```bash149anchor build --no-idl150```1514. **Check for nightly Rust interference:**152```bash153# IDL generation uses proc-macro2 which may need nightly features154# Override with stable:155RUSTUP_TOOLCHAIN=stable anchor build156```157158### `anchor build` error with `proc_macro2` / `local_file` method not found159```160error[E0599]: no method named `local_file` found for struct `proc_macro2::Span`161```162163**Cause:** proc-macro2 API change in newer nightly Rust.164165**Solutions:**1661. Upgrade to Anchor 0.31.1+ (fixed in [#3663](https://github.com/solana-foundation/anchor/pull/3663))1672. Use stable Rust: `RUSTUP_TOOLCHAIN=stable anchor build`1683. Pin proc-macro2: `cargo update -p proc-macro2 --precise 1.0.86`169170---171172## Installation Errors173174### `No space left on device` during Solana install175```176error: No space left on device (os error 28)177```178179**Cause:** Solana CLI + platform tools can use 2-5 GB. Multiple versions compound this.180181**Solutions:**1821. **Clean old versions:**183```bash184# List installed versions185ls ~/.local/share/solana/install/releases/186187# Remove old ones (keep only what you need)188rm -rf ~/.local/share/solana/install/releases/1.16.*189rm -rf ~/.local/share/solana/install/releases/1.17.*190191# Also clean cache192rm -rf ~/.cache/solana/193```1942. **Clean Cargo/Rust caches:**195```bash196cargo cache --autoclean # if cargo-cache is installed197# or manually:198rm -rf ~/.cargo/registry/cache/199rm -rf target/200```2013. **Clean AVM:**202```bash203ls ~/.avm/bin/204# Remove unused anchor versions205```206207### `agave-install` not found208```209error: agave-install: command not found210```211212**Cause:** Anchor CLI 0.31+ migrates to `agave-install` for Solana versions ≥1.18.19.213214**Solution:** Install via the Solana install script (which installs both):215```bash216sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"217```218219---220221## Testing Errors222223### `solana-test-validator` crashes or hangs224```225Error: failed to start validator226```227228**Solutions:**2291. **Kill existing validators:**230```bash231pkill -f solana-test-validator232# or233solana-test-validator --kill234```2352. **Clean ledger:**236```bash237rm -rf test-ledger/238```2393. **Check port availability:**240```bash241lsof -i :8899 # RPC port242lsof -i :8900 # Websocket port243```2444. **Consider Surfpool** as a modern alternative to `solana-test-validator`:245```bash246curl --proto '=https' --tlsv1.2 -LsSf https://github.com/txtx/surfpool/releases/latest/download/surfpool-installer.sh | sh247```248249### Anchor test fails with `Connection refused` / IPv6 issue250```251Error: connect ECONNREFUSED ::1:8899252```253254**Cause:** Node.js 17+ resolves `localhost` to IPv6 `::1` by default, but `solana-test-validator` binds to `127.0.0.1`.255256**Solutions:**2571. **Use Anchor 0.30+** which defaults to `127.0.0.1` instead of `localhost`2582. **Set NODE_OPTIONS:**259```bash260NODE_OPTIONS="--dns-result-order=ipv4first" anchor test261```2623. **Edit Anchor.toml:**263```toml264[provider]265cluster = "http://127.0.0.1:8899"266```267268---269270## Anchor Version Migration Issues271272### Anchor 0.29 → 0.30 Migration Errors273274**`accounts` method type errors in TypeScript:**275```276Argument of type '{ ... }' is not assignable to parameter of type 'ResolvedAccounts<...>'277```278279**Solution:** Change `.accounts({...})` to `.accountsPartial({...})` or remove auto-resolved accounts from the call.280281**Missing `idl-build` feature:**282```283Error: `idl-build` feature is missing284```285286**Solution:** Add to each program's Cargo.toml:287```toml288[features]289idl-build = ["anchor-lang/idl-build"]290```291292**`overflow-checks` not specified:**293```294Error: overflow-checks must be specified in workspace Cargo.toml295```296297**Solution:** Add to workspace `Cargo.toml`:298```toml299[profile.release]300overflow-checks = true301```302303### Anchor 0.30 → 0.31 Migration Errors304305**Solana v1 → v2 crate conflicts:**306```307error[E0308]: mismatched types308expected `solana_program::pubkey::Pubkey`309found `solana_sdk::pubkey::Pubkey`310```311312**Solution:** Remove direct `solana-program` and `solana-sdk` dependencies. Use them through `anchor-lang`:313```rust314use anchor_lang::prelude::*;315// NOT: use solana_program::pubkey::Pubkey;316```317318**`Discriminator` trait changes:**319```320error[E0277]: the trait bound `MyAccount: Discriminator` is not satisfied321```322323**Solution:** Ensure you derive `#[account]` on your structs. The discriminator is now dynamically sized.324325### Anchor 0.31 → 0.32 Migration Errors326327**`solana-program` dependency warning becomes error:**328Anchor 0.32 fully removes `solana-program` as a dependency. If your code imports from `solana_program::*`, change to the smaller crates:329```rust330// Before (0.31):331use solana_program::pubkey::Pubkey;332333// After (0.32):334use solana_pubkey::Pubkey;335// Or use anchor's re-export:336use anchor_lang::prelude::*;337```338339**Duplicate mutable accounts error:**340```341Error: Duplicate mutable account342```343Anchor 0.32+ disallows duplicate mutable accounts by default. Use the `dup` constraint:344```rust345#[derive(Accounts)]346pub struct MyInstruction<'info> {347#[account(mut)]348pub account_a: Account<'info, MyAccount>,349#[account(mut, dup = account_a)]350pub account_b: Account<'info, MyAccount>,351}352```353354---355356## Miscellaneous Errors357358### `solana airdrop` fails359```360Error: airdrop request failed361```362363**Cause:** Rate limiting on devnet/testnet.364365**Solutions:**3661. Wait and retry3672. Use the web faucet: https://faucet.solana.com3683. For testing, use localnet where airdrops are unlimited369370### Anchor IDL account authority mismatch371```372Error: Authority did not sign373```374375**Solution:** The IDL authority is the program's upgrade authority. Check with:376```bash377solana program show <PROGRAM_ID>378```379380### `declare_program!` not finding IDL file381```382Error: file not found: idls/my_program.json383```384385**Solution:** Place the IDL JSON in the `idls/` directory at the workspace root. The filename must match the program name (snake_case):386```387workspace/388├── idls/389│ └── my_program.json390├── programs/391│ └── my_program/392└── Anchor.toml393```394395---396397## LiteSVM Errors398399### `undefined symbol: __isoc23_strtol` (litesvm native binary)400```401Error: Cannot find native binding.402cause: litesvm.linux-x64-gnu.node: undefined symbol: __isoc23_strtol403```404405**Root cause:** LiteSVM 0.5.0 native binary is compiled against GLIBC 2.38+. The `__isoc23_strtol` symbol was introduced in GLIBC 2.38 (C23 standard functions). Systems with GLIBC < 2.38 (Ubuntu 22.04, Debian 12, etc.) cannot load this binary.406407**Verified on:** Debian 12 (GLIBC 2.36) — Jan 2026408409**Solutions:**4101. **Upgrade OS** to Ubuntu 24.04+ or Debian 13+ (recommended)4112. **Use Docker:**412```dockerfile413FROM ubuntu:24.04414RUN apt-get update && apt-get install -y nodejs npm415```4163. **Fall back to `solana-bankrun`** if you can't upgrade:417```bash418pnpm remove litesvm anchor-litesvm419pnpm add -D solana-bankrun anchor-bankrun420```4214. **Try litesvm 0.3.x** which may work on older GLIBC versions422423### `Cannot find module './litesvm.linux-x64-gnu.node'`424```425Error: Cannot find module './litesvm.linux-x64-gnu.node'426```427428**Root cause:** pnpm hoisting doesn't always correctly link native optional dependencies for native Node addons.429430**Solutions:**4311. Delete `node_modules` and reinstall: `rm -rf node_modules && pnpm install`4322. Use `node-linker=hoisted` in `.npmrc`:433```434node-linker=hoisted435```4363. Install the platform-specific package explicitly:437```bash438pnpm add -D litesvm-linux-x64-gnu439```440441---442443## Platform Tools Errors444445### `The Solana toolchain is corrupted` after fresh install446```447[ERROR cargo_build_sbf] The Solana toolchain is corrupted. Please, run cargo-build-sbf with the --force-tools-install argument to fix it.448```449450**Root cause:** Solana CLI 2.2.x downloads platform-tools v1.48 (~516MB compressed, ~2GB extracted). On systems with limited root partition space (<3GB free in `~/.cache/solana/`), extraction can fail silently, leaving a corrupted toolchain (e.g., `rust/` directory missing `rustc` binary).451452**Verified on:** Debian 12, Solana CLI 2.2.16, root partition 9.7GB with 2.1GB free — Jan 2026453454**Solutions:**4551. **Run with `--force-tools-install`:**456```bash457cargo build-sbf --force-tools-install458```459This re-downloads and re-extracts. Takes 5-10 minutes on average connections.4604612. **Ensure sufficient disk space** (~3GB free needed on partition containing `~/.cache/solana/`):462```bash463df -h ~/.cache/solana/464# If too small, symlink to bigger disk:465rm -rf ~/.cache/solana/v1.48/platform-tools466mkdir -p /mnt/data/solana-cache/v1.48/platform-tools467ln -sf /mnt/data/solana-cache/v1.48/platform-tools ~/.cache/solana/v1.48/platform-tools468```4694703. **Manual extraction** (if `--force-tools-install` keeps cycling):471```bash472# Download manually473wget https://github.com/anza-xyz/platform-tools/releases/download/v1.48/platform-tools-linux-x86_64.tar.bz2474# Extract to a disk with space475mkdir -p /mnt/data/solana-platform-tools/v1.48476cd /mnt/data/solana-platform-tools/v1.48477tar xjf /path/to/platform-tools-linux-x86_64.tar.bz2478# Symlink479ln -sf /mnt/data/solana-platform-tools/v1.48 ~/.cache/solana/v1.48/platform-tools480```481482**Note:** The `version.md` file is the last file extracted. Its presence confirms successful extraction.483484### Anchor CLI version mismatch warnings (non-fatal)485```486WARNING: `anchor-lang` version(0.32.1) and the current CLI version(0.30.1) don't match.487WARNING: `@coral-xyz/anchor` version(^0.32.1) and the current CLI version(0.30.1) don't match.488```489490**Root cause:** Using Anchor CLI 0.30.1 with `anchor-lang = "0.32.1"` in Cargo.toml. The build **succeeds** but prints warnings.491492**Verified on:** Debian 12, Anchor CLI 0.30.1 building anchor-lang 0.32.1 — builds and generates IDL correctly — Jan 2026493494**Impact:** Builds work. IDL generation works. But subtle runtime issues may occur with IDL format differences between 0.30 and 0.32.495496**Solutions:**4971. **Match versions** (recommended):498```toml499# Anchor.toml500[toolchain]501anchor_version = "0.32.1"502```503Then install matching CLI: `avm install 0.32.1`5042. **Or downgrade crate:** Change `anchor-lang = "0.30.1"` in Cargo.toml5053. **Ignore if just building:** The mismatch is cosmetic for `anchor build` and `anchor idl build`506507---508509## edition2024 Crate Incompatibility (Cargo 1.84.0)510511### `feature edition2024 is required` during `cargo build-sbf`512```513error: failed to download `constant_time_eq v0.4.2`514515Caused by:516failed to parse manifest at `.../constant_time_eq-0.4.2/Cargo.toml`517518Caused by:519feature `edition2024` is required520521The package requires the Cargo feature called `edition2024`, but that feature is not522stabilized in this version of Cargo (1.84.0 (12fe57a9d 2025-04-07)).523```524525**Root cause:** Platform-tools v1.48 (used by Solana CLI 2.2.16 and CI with Solana stable 3.0.14) bundles `cargo 1.84.0` (Solana Rust fork), which does **not** support `edition = "2024"`. Multiple crates in the Solana dependency tree have released versions requiring edition2024.526527### ⚠️ Known edition2024 Crates (Updated Jan 31, 2026)528529| Crate | Breaking Version | Safe Version | Pulled By |530|---|---|---|---|531| `blake3` | ≥1.8.3 | **1.8.2** | `solana-blake3-hasher` → `solana-program` |532| `constant_time_eq` | ≥0.4.2 | **0.3.1** | `blake3` |533| `base64ct` | ≥1.8.3 | **1.7.3** | `pkcs8`, `spki` → various crypto crates |534| `indexmap` | ≥2.13.0 | **2.11.4** | `toml_edit` → `proc-macro-crate` → `borsh-derive` → `anchor-lang` |535536**New crates may ship edition2024 at any time.** If you see this error with a crate not listed above, pin it to the previous version.537538**Why existing repos break:** Projects without a `Cargo.lock` (or with a stale one) resolve to the latest crate versions at build time, pulling in edition2024-requiring releases. This is especially common in CI environments.539540**Verified on:**541- Debian 12, Solana CLI 2.2.16, platform-tools v1.48 — Jan 30, 2026542- GitHub Actions (ubuntu-latest), Solana stable 3.0.14, Cargo 1.84.0 — Jan 31, 2026543544### Solutions545546**1. Pin all known problematic crates (recommended for CI):**547```bash548cargo generate-lockfile549cargo update -p blake3 --precise 1.8.2550cargo update -p constant_time_eq --precise 0.3.1551cargo update -p base64ct --precise 1.7.3552cargo update -p indexmap --precise 2.11.4553```554555**2. Pin via workspace Cargo.toml:**556```toml557# In workspace Cargo.toml558[workspace.dependencies]559blake3 = "=1.8.2"560base64ct = "=1.7.3"561```562563**3. Always commit Cargo.lock for programs and Anchor projects:**564```bash565# Force-add if .gitignore excludes it566git add -f Cargo.lock567```568This is the single most effective prevention — a committed lockfile prevents cargo from resolving to newer breaking versions.569570**4. For monorepos with per-project Cargo.lock files (e.g., program-examples):**571Each Anchor project that has its own `Cargo.toml` outside the workspace needs its own `Cargo.lock`. Generate and pin for each:572```bash573for dir in $(find . -path "*/anchor/Cargo.toml" -exec dirname {} \;); do574cd "$dir"575cargo generate-lockfile576cargo update -p blake3 --precise 1.8.2 2>/dev/null577cargo update -p constant_time_eq --precise 0.3.1 2>/dev/null578cargo update -p base64ct --precise 1.7.3 2>/dev/null579cargo update -p indexmap --precise 2.11.4 2>/dev/null580cd -581done582git add -f **/Cargo.lock583```584585**5. Wait for platform-tools update** — a future platform-tools version will ship a cargo that supports edition2024. Track at [anza-xyz/platform-tools](https://github.com/anza-xyz/platform-tools/releases).586587### `Could not find specification for target "sbpf-solana-solana"` with `--tools-version`588```589error: Error loading target specification: Could not find specification for target "sbpf-solana-solana".590Run `rustc --print target-list` for a list of built-in targets591```592593**Root cause:** Using `cargo build-sbf --tools-version v1.43` with Solana CLI 2.2.16. The CLI generates `--target sbpf-solana-solana` but platform-tools v1.43 only knows older target triples (e.g., `sbf-solana-solana`). The SBPF target rename happened between v1.43 and v1.48.594595**Verified on:** Debian 12, Solana CLI 2.2.16 — Jan 30, 2026596597**Solution:** Don't downgrade platform-tools below your CLI's default version. Use the default tools version (v1.48 for CLI 2.2.16).598599---600601## Verified Test Results (Debian 12, Jan 2026)602603Environment: Rust 1.93, Solana CLI 2.2.16, Anchor CLI 0.30.1, Node 22.22.0, GLIBC 2.36604605| Test | Command | Result | Notes |606|------|---------|--------|-------|607| Anchor CLI/crate mismatch | `anchor build` (CLI 0.30.1 / anchor-lang 0.32.1) | ⚠️ PASS with warnings | Builds succeed; prints version mismatch warnings |608| cargo build-sbf (native) | `cargo build-sbf` on hello-solana, counter, transfer-sol, create-account, checking-accounts | ✅ PASS | All build after platform-tools v1.48 installed correctly |609| solana-bankrun (GLIBC 2.36) | `npm install solana-bankrun && require('solana-bankrun')` | ✅ PASS | `start` function available, works on GLIBC 2.36 |610| litesvm npm (GLIBC 2.36) | `npm install litesvm && require('litesvm')` | ❌ FAIL | `undefined symbol: __isoc23_strtol` — requires GLIBC ≥2.38 |611| @solana/web3.js CJS | `require('@solana/web3.js')` | ✅ PASS | Keypair, Connection etc. available |612| @solana/web3.js ESM | `import * as web3 from '@solana/web3.js'` | ✅ PASS | Full ESM support on Node 22 |613| @solana/kit (web3.js v2) ESM | `import('@solana/kit')` | ✅ PASS | ESM-only, works on Node 22 |614| @coral-xyz/anchor CJS | `require('@coral-xyz/anchor')` | ✅ PASS | Program, Provider etc. available |615| @coral-xyz/anchor ESM | `import * as anchor from '@coral-xyz/anchor'` | ✅ PASS | Full ESM support on Node 22 |616| IDL generation | `anchor idl build` (from program dir) | ✅ PASS | Generates valid JSON IDL with CLI 0.30.1 |617| Cargo duplicate deps | `cargo tree -d` on program-examples | ⚠️ INFO | 2295 lines of duplicate deps (ahash, base64, borsh, curve25519-dalek, ed25519-dalek, etc.) — normal for Solana workspace |618| Platform tools corruption | `cargo build-sbf` on fresh install | ❌ FAIL then PASS | Initial corruption due to disk space; fixed with `--force-tools-install` on adequate disk |619620### Key Findings6211. **litesvm 0.5.0 npm is BROKEN on Debian 12** (GLIBC 2.36) — use `solana-bankrun` as fallback6222. **solana-bankrun works perfectly** on GLIBC 2.36 — recommended for Debian 126233. **Platform-tools v1.48 needs ~2GB disk** for extraction — symlink `~/.cache/solana/` to a larger partition if root is small6244. **Anchor CLI 0.30.1 successfully builds anchor-lang 0.32.1** — warnings only, no errors6255. **Node 22 has full ESM+CJS support** for all Solana JS packages tested6266. **Cargo duplicate dependencies are normal** in Solana monorepos (borsh 0.9/0.10/1.x, curve25519-dalek 3.x/4.x, etc.)627