Troubleshooting Guide

Solutions for common issues when building and running RISC Zero zkVM applications

Installation Issues

rzup installation fails

Symptoms:

• rzup command not found
• Installation script errors

Solutions:

1. Ensure prerequisites are installed:

   # Rust
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   
   # Git LFS
   git lfs install
   

2. Reinstall rzup:

   curl -L https://risczero.com/install | bash
   rzup install
   

3. Check PATH configuration: Ensure ~/.cargo/bin is in your PATH:

   echo $PATH | grep cargo
   

After installation, restart your terminal or run source ~/.bashrc (or ~/.zshrc).

RISC Zero toolchain version mismatch

Symptoms:

• “Version mismatch” errors
• Compilation failures after updating

Solution:

Ensure your toolchain version matches your project’s risc0-zkvm version:

# For development branches
cargo install --force --path risc0/cargo-risczero

# For stable versions
cargo install cargo-risczero
rzup install

When using DefaultProver, the cargo-risczero version must match the risc0-zkvm crate version.

Build Errors

Guest build fails with missing dependencies

Symptoms:

• Linker errors
• Missing symbol errors (e.g., _end)

Solutions:

1. Install the RISC Zero toolchain:

   cargo run --bin rzup install rust
   cargo run --bin rzup install cpp
   

2. Verify toolchain installation:

   rustup toolchain list | grep risc0
   

3. Clean and rebuild:

   cargo clean
   cargo build --release
   

RISC0_SKIP_BUILD errors

Symptoms:

• Clippy or IDE errors about missing guest methods

Solution:

When running clippy or IDE analysis, set RISC0_SKIP_BUILD=1 to skip guest compilation:

RISC0_SKIP_BUILD=1 cargo clippy

This skips time-consuming guest builds during development.

Reproducible build fails in Docker

Symptoms:

• Docker build errors
• Feature flag issues in Docker

Solution:

Use the cargo risczero build command for deterministic builds:

cargo risczero build --manifest-path path/to/guest/Cargo.toml

This runs the build inside a Docker container to ensure reproducibility.

Ensure Docker is installed and running before using cargo risczero build.

Runtime Errors

Guest program panics or exits unexpectedly

Debugging steps:

1. Enable debug logging:

   RUST_LOG=info cargo run
   

2. Add debug output in guest:

   risc0_zkvm::guest::env::log("Debug checkpoint reached");
   

3. Use GDB for debugging: See the Debugging with GDB guide for detailed instructions.

4. Check for common issues:

   • Stack overflows (increase stack size if needed)
   • Out of memory (use the embedded allocator for long-running programs)
   • Unsupported syscalls

Set RISC0_INFO=1 to get profiling information that may help identify where the guest is failing.

Environment variables not working in guest

Symptoms:

• std::env::var() fails or panics
• Environment variable access errors

Explanation:

Environment syscalls (sys_getenv, sys_argc, sys_argv) are disabled by default for security reasons. Code designed for the host may behave insecurely in the guest.

Solution:

Enable environment variables via the RISC0_GUEST_LOGENV feature flag on risc0-zkvm-platform if absolutely necessary:

[dependencies]
risc0-zkvm-platform = { version = "*", features = ["RISC0_GUEST_LOGENV"] }

Enabling environment variables in the guest can introduce security risks. Use with caution.

Proof generation fails or hangs

Possible causes and solutions:

1. Insufficient memory:

   • Close other applications
   • Use GPU proving for better memory efficiency
   • Split computation using continuations

2. GPU driver issues:

   # Test CPU proving first
   RISC0_PROVER=cpu cargo run --release
   

3. Version compatibility:

   • Ensure all RISC Zero crates use the same version
   • Update dependencies: cargo update

4. Use execute-only mode for testing: Execute without proving to verify guest logic:

   let env = ExecutorEnv::builder().build()?;
   let session = executor.execute(env, GUEST_ELF)?;
   

Receipt verification fails

Common issues:

1. Image ID mismatch:

   • Ensure the verifier uses the correct Image ID
   • Rebuild the guest if the code changed

2. Control ID version mismatch:

   • Prover and verifier must use the same zkVM version
   • Check that all dependencies match

3. Corrupted receipt:

   • Verify serialization/deserialization is correct
   • Check network transmission didn’t corrupt data

Receipts from zkVM 1.0.x cannot be verified with verifiers from 1.1.x due to zero-knowledge improvements. Always match prover and verifier versions.

Performance Issues

Proof generation is too slow

Optimization strategies:

1. Enable GPU proving:

   # CUDA
   cargo run --release -F cuda
   
   # Metal (macOS)
   cargo run --release -F metal
   

2. Profile your guest code:

   RISC0_INFO=1 cargo run --release
   

3. Use precompiles for cryptographic operations

4. Optimize guest code:

   • See the Optimization Guide
   • Reduce unnecessary computation
   • Use efficient algorithms

5. Consider proof composition: Split large computations into smaller proofs that can be composed

High cycle count

Investigation steps:

1. Profile with RISC0_INFO:

   RISC0_INFO=1 cargo run --release
   

2. Check for inefficient operations:

   • Memory allocations
   • String operations
   • Large data structures

3. Use precompiles where applicable:

   • SHA-256: Use the accelerated SHA extension
   • BigInt: Use risc0-bigint2 for modular arithmetic
   • Keccak: Use the keccak precompile
   • ECDSA: Use accelerated signature verification

See the Precompiles documentation for more details.

Rust-Specific Issues

std not available in guest

Symptoms:

• “std not found” errors in guest code

Solution:

The guest runs in a no_std environment by default. Import the guest standard library:

#![no_std]
#![no_main]

use risc0_zkvm::guest::env;

For allocations, enable the alloc crate:

extern crate alloc;
use alloc::vec::Vec;

Crate not compatible with RISC-V

Symptoms:

• Build errors with third-party crates
• “not found” errors for std types

Solution:

Check if the crate supports no_std and RISC-V:

1. Look for no_std support in the crate documentation
2. Check the supported crates list
3. Consider alternatives or implement the functionality yourself

Some crates require C bindings. See Rust Crates with C++ Bindings for guidance.

thread_local! crashes the guest

Solution:

Use Rust toolchain version r0.1.79.0-1 or later. Earlier versions have a bug with thread_local! in combination with the heap allocator.

Update your toolchain:

rzup install

Testing and CI

Tests are too slow

Solutions:

1. Use dev mode for rapid testing without proving:

   RISC0_DEV_MODE=1 cargo test
   

2. Skip guest builds during unit tests:

   RISC0_SKIP_BUILD=1 cargo test
   

3. Use light builds for development: Light builds are faster but not production-ready.

Never use dev mode in production. It skips proof generation entirely.

CI/CD pipeline issues

Common solutions:

1. Install Git LFS in CI:

   git lfs install
   git lfs pull
   

2. Cache dependencies: Cache ~/.cargo and target/ directories

3. Use consistent toolchain versions: Pin versions in your CI configuration

4. Docker support: Ensure Docker is available for reproducible builds

Getting Help

If you can’t find a solution here:

GitHub Issues

Search existing issues or open a new one

Discord

Ask questions in the community

Known Workarounds

Check tagged workarounds on GitHub

FAQ

Common questions and answers

When reporting issues, include:

• RISC Zero version (cargo tree | grep risc0)
• Rust version (rustc --version)
• Operating system and architecture
• Minimal reproduction case
• Error messages and logs