> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/a16z/jolt/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
cargo install --path . --locked
```

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

### Missing Toolchain

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

**Solution:** Ensure you're using the correct Rust nightly version:

```bash theme={null}
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:

```bash theme={null}
# 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 { ... }
```

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

## 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:

```bash theme={null}
# 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:

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

2. **Profile memory usage** to identify bottlenecks:

```bash theme={null}
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:

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

<Tip>
  Start with conservative values and increase as needed. Larger values consume more memory during proving.
</Tip>

## Performance Issues

### Slow Proving Times

**Symptom:** Proof generation takes longer than expected.

**Solutions:**

1. **Always use release builds** for proving:

```bash theme={null}
cargo run --release -p example
```

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

2. **Profile your program** to identify bottlenecks:

```bash theme={null}
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:

```bash theme={null}
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:**

```bash theme={null}
# Use cargo nextest, not cargo test
cargo nextest run --cargo-quiet
```

2. **Run specific tests:**

```bash theme={null}
cargo nextest run -p jolt-core muldiv --cargo-quiet
```

3. **Test in both standard and ZK modes:**

```bash theme={null}
# 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
```

<Note>
  Always use `cargo nextest` instead of `cargo test` when working with Jolt. The project is configured for nextest.
</Note>

## Verification Issues

### Proof Verification Failures

**Symptom:** Generated proofs fail verification.

**Solutions:**

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

```rust theme={null}
// 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:**

```rust theme={null}
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:

```rust theme={null}
// 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);
```

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

### jolt-emu Not Found

**Symptom:** `jolt run` command fails with "jolt-emu not found" error.

**Solutions:**

1. **Build jolt-emu:**

```bash theme={null}
cargo build --release -p jolt-emu
```

2. **Specify path explicitly:**

```bash theme={null}
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:**

```bash theme={null}
export PATH=$PATH:$(pwd)/target/release
jolt run mybinary
```

## Getting Help

<Note>
  If you encounter issues not covered in this guide:

  1. Check the [Jolt Book](https://jolt.a16zcrypto.com/) for detailed documentation
  2. Search existing [GitHub issues](https://github.com/a16z/jolt/issues)
  3. Open a new issue with a minimal reproducible example
  4. Include relevant error messages, logs, and your environment details
</Note>

## Alpha Software Warning

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

## 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