Skip to main content
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
}
  1. Profile memory usage to identify bottlenecks:
RUST_LOG=debug cargo run --release --features allocative -p jolt-core profile --name myprogram --format chrome
  1. 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.
  1. Profile your program to identify bottlenecks:
cargo run --release --features monitor -p jolt-core profile --name myprogram --format chrome
  1. 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
  1. Run specific tests:
cargo nextest run -p jolt-core muldiv --cargo-quiet
  1. 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
  1. 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
);
  1. 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
  1. 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
  1. 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

Build docs developers (and LLMs) love

Get started for freeTalk to us