Skip to content
Ashen Docs

Troubleshooting

This guide lists common failures and quick fixes. Format: Error message -> Solution.

Build Failures

Section titled “Build Failures”

  • “zig: command not found” -> Install Zig and re-run zig build for contracts.

  • “error: target ‘riscv64imac-unknown-none-elf’ not found” -> rustup target add riscv64imac-unknown-none-elf or use devenv shell.

  • “error: could not compile” after toolchain drift -> Use the pinned toolchain in devenv.nix (devenv shell).

  • “linker cc not found” -> Install a system C toolchain (or enter devenv shell).

Test Failures

Section titled “Test Failures”

  • “proptest: Failed” with a seed -> Re-run with PROPTEST_SEED=<seed> PROPTEST_CASES=1 cargo test -p <crate> <test>.

  • Non-deterministic failures -> Re-run with RUST_TEST_THREADS=1 and -- --nocapture for logs.

  • devnet_replay golden mismatch -> Re-run with REGENERATE_GOLDENS=1 cargo test --test devnet_replay.

Node Startup Issues

Section titled “Node Startup Issues”

  • “address already in use” -> Stop the other process or change ports (e.g., --listen, --p2p-port).

  • “genesis not found at … (run devnet-node init --data-dir ... first)” -> Run just devnet-node init --data-dir <dir>.

  • “peers.yaml not found. Run ‘just testnet-local-generate’ first.” -> Run just testnet-local-generate.

  • “keystore not found … run ‘ashen keystore init’ first” -> Run just ashen keystore init.

Contract Deployment Errors

Section titled “Contract Deployment Errors”

  • “ASHEN_PRIVATE_KEY is required” -> Set ASHEN_PRIVATE_KEY=@/path/to/key.json or export a hex key.

  • “ELF validation failed” -> Build with the contract target (just contract-build) and re-run just vm-elf-validate.

  • “RPC 401 Unauthorized” -> Set NODE_AUTH_TOKEN for the node you are calling.

  • “contract not found” / “account not found” -> Confirm the deployment address and that the node is running.