Troubleshooting

Common issues and solutions when working with Jolt zkVM

This guide covers common issues you might encounter when working with Jolt zkVM and their solutions.

Build Issues

Guest Build Failures After Pulling Changes

Symptom: Guest builds fail after pulling the latest changes from the repository.

Solution: Reinstall the Jolt CLI:

cargo install --path . --locked

After pulling changes that affect the Jolt CLI, you must reinstall it to ensure guest builds use the latest version.

Missing Toolchain

Symptom: Build errors related to Rust toolchain or target not found.

Solution: Ensure you’re using the correct Rust nightly version:

cd jolt
rustup show

If rustup is installed, it should automatically install the correct toolchain specified in rust-toolchain.toml.

Symbol Stripping Issues

Symptom: Backtraces show no function names or source locations.

Solution: Enable symbol preservation:

# Via environment variable (temporary)
JOLT_BACKTRACE=1 cargo run --release -p example

# Via CLI flag (for this build)
jolt build --backtrace enable

# Via attribute (permanent for this function)
#[jolt::provable(backtrace = "dwarf")]
fn my_function(input: u64) -> u64 { ... }

Symbols are stripped by default in release builds. Always use one of the above methods when you need readable backtraces.

Runtime Issues

Guest Panics Without Stack Trace

Symptom: Guest program panics but shows no useful debugging information.

Solution: Enable JOLT_BACKTRACE to get detailed panic information:

# Basic backtrace with symbols
JOLT_BACKTRACE=1 cargo run --release -p example

# Full backtrace with register snapshots
JOLT_BACKTRACE=full cargo run --release -p example

Out of Memory Errors

Symptom: Program crashes with out-of-memory errors during proving.

Solutions:

1. Increase heap size in your #[jolt::provable] attribute:

#[jolt::provable(heap_size = 65536)]  // Increase from default 32768
fn my_function(input: u64) -> u64 {
    // Your code
}

2. Profile memory usage to identify bottlenecks:

RUST_LOG=debug cargo run --release --features allocative -p jolt-core profile --name myprogram --format chrome

3. Optimize your guest code to use less memory.

Trace Length Exceeded

Symptom: Error about maximum trace length being exceeded.

Solution: Increase max_trace_length in your #[jolt::provable] attribute:

#[jolt::provable(max_trace_length = 131072)]  // Increase from default 65536
fn my_function(input: u64) -> u64 {
    // Your code
}

Start with conservative values and increase as needed. Larger values consume more memory during proving.

Performance Issues

Slow Proving Times

Symptom: Proof generation takes longer than expected.

Solutions:

1. Always use release builds for proving:

cargo run --release -p example

Debug builds can be orders of magnitude slower. Never benchmark or measure performance with debug builds.

2. Profile your program to identify bottlenecks:

cargo run --release --features monitor -p jolt-core profile --name myprogram --format chrome

3. Optimize guest code:
   • Reduce unnecessary computations
   • Minimize memory allocations
   • Use efficient algorithms

High Memory Usage During Proving

Symptom: Prover consumes excessive memory.

Solution: Use memory profiling to identify heavy allocations:

RUST_LOG=debug cargo run --release --features allocative -p jolt-core profile --name myprogram --format chrome

Analyze the generated flamegraph SVG files to identify memory-intensive stages.

Testing Issues

Tests Failing After Code Changes

Symptom: Tests that previously passed now fail.

Solutions:

1. Run tests with the correct command:

# Use cargo nextest, not cargo test
cargo nextest run --cargo-quiet

2. Run specific tests:

cargo nextest run -p jolt-core muldiv --cargo-quiet

3. Test in both standard and ZK modes:

# Standard mode
cargo nextest run -p jolt-core muldiv --cargo-quiet --features host

# ZK mode
cargo nextest run -p jolt-core muldiv --cargo-quiet --features host,zk

Always use cargo nextest instead of cargo test when working with Jolt. The project is configured for nextest.

Verification Issues

Proof Verification Failures

Symptom: Generated proofs fail verification.

Solutions:

1. Check for transcript mismatches — ensure prover and verifier use the same inputs:

// Prover and verifier must receive identical inputs
let (output, proof, io_device) = prove_fib(50);
let is_valid = verify_fib(50, output, io_device.panic, proof);  // Same input: 50

2. Verify you’re using matching preprocessing:

let shared_preprocessing = guest::preprocess_shared_fib(&mut program);
let prover_preprocessing = guest::preprocess_prover_fib(shared_preprocessing.clone());
let verifier_preprocessing = guest::preprocess_verifier_fib(
    shared_preprocessing,  // Same shared preprocessing
    verifier_setup
);

3. Check for code changes that might affect proof generation.

Development Workflow Issues

Slow Iteration During Development

Symptom: Testing changes takes too long due to full proof generation.

Solution: Use trace_analyze instead of the full prover:

// Fast iteration during development
let (output, io_device) = trace_analyze_my_function(input);

// Full proving only when needed
let (output, proof, io_device) = prove_my_function(input);

During development, use trace_analyze to test guest logic without proof generation overhead. Switch to full proving once the logic is correct.

jolt-emu Not Found

Symptom: jolt run command fails with “jolt-emu not found” error.

Solutions:

1. Build jolt-emu:

cargo build --release -p jolt-emu

2. Specify path explicitly:

jolt run --jolt-emu /path/to/jolt-emu mybinary

# Or set environment variable
export JOLT_EMU_PATH=/path/to/jolt-emu
jolt run mybinary

3. Ensure jolt-emu is in PATH:

export PATH=$PATH:$(pwd)/target/release
jolt run mybinary

Getting Help

If you encounter issues not covered in this guide:

1. Check the Jolt Book for detailed documentation
2. Search existing GitHub issues
3. Open a new issue with a minimal reproducible example
4. Include relevant error messages, logs, and your environment details

Alpha Software Warning

Jolt is in alpha and is not suitable for production use at this time. Expect breaking changes and evolving APIs.

Environment Information

When reporting issues, include:

• Operating system and version
• Rust toolchain version (rustup show)
• Jolt version (jolt --version)
• Relevant error messages and logs
• Steps to reproduce the issue