Skip to main content

Troubleshooting

This guide covers common issues you may encounter when building and running Ligetron, with solutions organized by symptoms. Most build-time issues are related to web builds, which have additional complexity due to WebAssembly compilation requirements.

Quick Diagnosis
  • Emscripten flags not recognized → Use emcmake cmake instead of plain cmake
  • WebGPU header conflicts → Check and unset CPATH environment variable
  • Install fails with "cannot create directory: /lib" → Set $WASM_LIBS before running cmake
  • Missing boost_iostreams → Build WebAssembly version of Boost (see Building Dependencies)
  • Architecture mismatch → Use WebAssembly-compiled libraries, not system libraries from Homebrew/apt

Web Build Issues​

Error: "unknown argument: '-sUSE_ZLIB=1'"​

Full error message:

clang++: error: unknown argument: '-sUSE_ZLIB=1'
clang++: error: unknown argument: '-sUSE_BOOST_HEADERS=1'

Symptom: CMake configuration succeeds, but make -j fails immediately with clang++ errors about unrecognized Emscripten flags.

Root cause: CMake is using the system compiler (/usr/bin/clang++) instead of Emscripten's compiler wrapper (em++). Plain cmake doesn't automatically detect that you want to use Emscripten.

Solution:

# Wrong - uses system compiler
cmake -DCMAKE_BUILD_TYPE=Web ..

# Correct - uses Emscripten
source /path/to/emsdk/emsdk_env.sh
emcmake cmake -DCMAKE_BUILD_TYPE=Web \
      -DCMAKE_PREFIX_PATH=$WASM_LIBS ..

Key points:

  • Always use emcmake cmake (not plain cmake) for web builds
  • Source emsdk_env.sh before running emcmake
  • This sets up the Emscripten toolchain file and compiler wrappers

Error: WebGPU Header Conflicts​

Full error message:

error: no viable overloaded '='
note: candidate function not viable: no known conversion from 'const char *' to 'WGPUStringView' for 1st argument

Symptom: Web build fails during compilation with errors about WGPUStringView type mismatches in WebGPU headers.

Root cause: The CPATH environment variable includes system include paths (like /usr/local/include) that contain Dawn's native WebGPU headers. These conflict with Emscripten's built-in WebGPU headers, which use different API signatures.

Diagnosis:

Check your shell profile files:

cat ~/.zprofile | grep CPATH
cat ~/.zshrc | grep CPATH

If you see something like:

export CPATH="/usr/local/include:/opt/homebrew/include"

This will cause conflicts during web builds.

Solution:

Temporarily unset CPATH before building:

cd build-web
unset CPATH
source /path/to/emsdk/emsdk_env.sh
emcmake cmake -DCMAKE_BUILD_TYPE=Web \
      -DCMAKE_PREFIX_PATH=$WASM_LIBS ..
make -j

Better long-term solution: Remove or comment out the CPATH export from your ~/.zprofile:

# Comment this out or remove it
# export CPATH="/usr/local/include:/opt/homebrew/include"

Then use CMAKE_PREFIX_PATH instead to specify dependency locations on a per-project basis.

Why This Happens

Dawn (used for native builds) and Emscripten (used for web builds) both provide WebGPU headers, but with different API versions. Dawn's headers in /usr/local/include should only be used for native builds. For web builds, Emscripten provides its own WebGPU implementation that matches browser APIs.

Error: Missing libboost_iostreams.a​

Full error message:

undefined symbol: boost::iostreams::zlib::default_strategy (referenced by top-level compiled C/C++ code)
undefined symbol: boost::iostreams::zlib_error::check(int) (referenced by top-level compiled C/C++ code)

Symptom: Web build linker fails with undefined symbols related to boost::iostreams::zlib.

Root cause: Ligetron added gzip compression for proofs in version 1.1.0, which requires the boost::iostreams library. This library must be compiled specifically for WebAssembly - system-installed versions from Homebrew or apt cannot be used.

Solution:

You need to build Boost (including iostreams) for WebAssembly. Follow the comprehensive instructions in Building Dependencies: Building WebAssembly Dependencies for Web Builds.

The section includes complete step-by-step instructions for building:

  • boost::iostreams (for proof compression)
  • boost::serialization (for proof data)
  • boost::log (for logging)
  • boost::exception (for error handling)

Quick summary:

  1. Set up a WebAssembly library directory:

    mkdir -p ~/ligetron-deps/wasm_libs
    export WASM_LIBS=~/ligetron-deps/wasm_libs

  2. Build Boost with Emscripten (see full instructions)

  3. Use the libraries when building Ligetron for web:

    emcmake cmake -DCMAKE_BUILD_TYPE=Web \
          -DCMAKE_PREFIX_PATH=$WASM_LIBS ..
Cannot Use System Libraries

You cannot use the boost::iostreams library installed via Homebrew or apt for web builds. System libraries are compiled for your native CPU architecture (x86_64 or arm64), not for WebAssembly (wasm32). Attempting to link them will result in architecture mismatch errors.

Error: Architecture Mismatch​

Example error messages:

ld: warning: ignoring file 'libboost_serialization.a': found architecture 'arm64', required architecture 'wasm32'

or

error: undefined reference to 'boost::serialization::...'

Symptom: Linker warnings about architecture mismatches, followed by undefined reference errors.

Root cause: You're trying to link native libraries (from Homebrew/apt) with WebAssembly code. System package managers install libraries compiled for your CPU architecture (x86_64, arm64), not for WebAssembly (wasm32).

Solution:

Always use WebAssembly-compiled libraries for web builds. You must build these yourself using Emscripten:

# Correct - using WebAssembly libraries
export WASM_LIBS=~/ligetron-deps/wasm_libs
emcmake cmake -DCMAKE_BUILD_TYPE=Web \
      -DCMAKE_PREFIX_PATH=$WASM_LIBS ..

# Wrong - tries to use system libraries
emcmake cmake -DCMAKE_BUILD_TYPE=Web \
      -DCMAKE_PREFIX_PATH=/usr/local ..

Required WebAssembly libraries:

  • libboost_serialization.a - For proof data serialization
  • libboost_iostreams.a - For proof compression (required since v1.1.0)
  • libboost_log.a - For logging
  • libboost_exception.a - For exception handling
  • libgmp.a, libgmpxx.a - For arbitrary precision arithmetic
  • libssl.a, libcrypto.a - For cryptography
  • libwabt.a - For WebAssembly parsing

See Building WebAssembly Dependencies for complete build instructions for all required libraries.

Why This Matters

WebAssembly is a completely different instruction set architecture than x86_64 or ARM. Libraries must be compiled specifically for the wasm32 target using Emscripten. Each library needs special configuration flags and toolchain settings to build correctly for WebAssembly.

WebAssembly Dependency Build Issues​

Error: "file cannot create directory: /lib"​

Full error message:

CMake Error at cmake_install.cmake:41 (file):
  file cannot create directory: /lib.  Maybe need administrative privileges.
make: *** [install] Error 1

Symptom: Building WebAssembly dependencies (GMP, OpenSSL, wabt) succeeds, but make install or emmake make install fails trying to write to /lib instead of the intended installation directory.

Root cause: The $WASM_LIBS environment variable was not set (or not exported) when running cmake or emcmake cmake. This causes CMAKE_INSTALL_PREFIX to be empty, and the build system defaults to system directories like /lib.

Solution:

Always ensure $WASM_LIBS is set before configuring any WebAssembly dependency:

# Set the environment variable
export WASM_LIBS=~/ligetron-deps/wasm_libs

# Then reconfigure with the correct prefix
cd build-directory
rm -rf *  # Clean the build directory
source /path/to/emsdk/emsdk_env.sh

# For libraries that use emcmake (wabt, etc.)
emcmake cmake -DCMAKE_INSTALL_PREFIX=$WASM_LIBS ..
make -j
make install

# For libraries that set CC directly (OpenSSL, etc.)
CC=emcc AR=emar RANLIB=emranlib ./Configure --prefix=$WASM_LIBS ...
make -j
make install

Verification:

After reconfiguring, verify the install prefix is correct:

grep CMAKE_INSTALL_PREFIX CMakeCache.txt
# Should show: CMAKE_INSTALL_PREFIX:PATH=/path/to/your/wasm_libs
tip

Add export WASM_LIBS=~/ligetron-deps/wasm_libs to your shell profile (~/.bashrc or ~/.zshrc) to avoid having to set it in every terminal session.

Native Build Issues​

Error: Dawn Headers Not Found​

Symptom: CMake configuration fails with errors like:

Could not find Dawn headers in /usr/local/include/dawn

Root cause: Dawn (WebGPU) is not installed, or not installed in the expected location.

Solution:

Build and install Dawn following the instructions in Building Dependencies: WebGPU.

Verify installation:

ls /usr/local/include/dawn
ls /usr/local/lib/libdawn*

Error: GCC Version Too Old (Ubuntu)​

Symptom: Compilation fails with C++20 feature errors like:

error: 'std::format' is not a member of 'std'

Root cause: Ligetron requires GCC 13 or newer for full C++20 support.

Solution:

Install and set GCC 13 as default:

# Add Ubuntu Toolchain PPA
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt update

# Install GCC 13
sudo apt install g++-13 -y

# Set as default
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-13 20
sudo update-alternatives --set g++ "/usr/bin/g++-13"

# Verify
g++ --version  # Should show version 13 or higher

Then clean and rebuild:

cd build
rm -rf *
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j

SDK Build Issues​

Error: SDK Not Built Before Prover​

Symptom: Native or web build fails with errors about missing SDK headers or libraries.

Root cause: The SDK must be built before building the prover/verifier executables.

Solution:

Always build the SDK first:

# 1. Build the SDK
cd sdk/cpp
mkdir -p build && cd build
source /path/to/emsdk/emsdk_env.sh
emcmake cmake ..
make -j

# 2. Then build the prover/verifier
cd ../../..  # back to ligetron root

# For native builds:
mkdir -p build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j

# For web builds:
mkdir -p build-web && cd build-web
unset CPATH
source /path/to/emsdk/emsdk_env.sh
emcmake cmake -DCMAKE_BUILD_TYPE=Web \
      -DCMAKE_PREFIX_PATH=$WASM_LIBS ..
make -j

Error: Linking errors when building custom WASM​

Symptom: Undefined symbol errors during linking

Solution: Ensure you're linking with the Ligetron library:

em++ -O2 \
     -I/path/to/sdk/cpp/include \
     -L/path/to/sdk/cpp/build \
     my_app.cpp \
     -o my_app.wasm \
     -lligetron  # Important!

Runtime Issues​

Error: "Failed to create WebGPU adapter"​

Symptom: Prover executable runs but fails immediately with:

Failed to create WebGPU adapter

Root cause: No compatible GPU or graphics API available.

Possible causes and solutions:

  1. Metal not available: Ensure you're running on macOS 10.13 or later with Metal support
  2. Running over SSH: WebGPU requires direct GPU access and doesn't work over remote connections
  3. GPU drivers: Update macOS to the latest version

Error: Proof verification fails​

Symptom: Verifier returns "Invalid proof"

Solutions:

  1. Check configuration consistency: Ensure prover and verifier use identical JSON configuration (except private arguments)
# Prover
./webgpu_prover '{"program":"app.wasm","packing":8192,...}'

# Verifier must use SAME packing size
./webgpu_verifier '{"program":"app.wasm","packing":8192,...}'

  1. Verify constraint logic: Ensure your application generates correct constraints

  2. Check private indices: Ensure private-indices array matches between prover and verifier

Error: Out of memory during proof generation​

Symptom: Prover crashes or reports out-of-memory error

Solutions:

  1. Reduce packing size:
./webgpu_prover '{"program":"app.wasm","packing":4096,...}'

  1. Simplify the circuit: Reduce the number of constraints in your application

  2. Use fewer constraints: Avoid unnecessary _checked operations

Error: Slow proof generation​

Solutions:

  1. Increase GPU threads:
./webgpu_prover '{..., "gpu-threads": 16384, ...}'

  1. Optimize constraints: Use vectorized operations and minimize constraint depth

  2. Check GPU utilization: Ensure GPU is being used (check with nvidia-smi on NVIDIA GPUs)

Error: Browser WebGPU not working​

Symptom: Web version fails to initialize WebGPU

Solutions:

  1. Use a supported browser: Chrome or Edge with WebGPU support

  2. Enable WebGPU flags (if needed):

# Linux
google-chrome --enable-unsafe-webgpu --enable-features=Vulkan

# macOS/Windows
# Usually works without flags
  1. Check browser support: Visit https://webgpureport.org/ to verify WebGPU is available

General Tips​

Clean Build​

If you encounter persistent errors, try a clean build:

# Clean native build
rm -rf build
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j

# Clean web build
rm -rf build-web
mkdir build-web && cd build-web
unset CPATH
source /path/to/emsdk/emsdk_env.sh
emcmake cmake -DCMAKE_BUILD_TYPE=Web \
      -DCMAKE_PREFIX_PATH=$WASM_LIBS ..
make -j

Check CMake Cache​

To see what CMake detected during configuration:

cd build
cat CMakeCache.txt | grep CMAKE_CXX_COMPILER
cat CMakeCache.txt | grep CMAKE_PREFIX_PATH

For web builds, verify:

  • CMAKE_CXX_COMPILER should point to Emscripten's em++
  • CMAKE_TOOLCHAIN_FILE should point to Emscripten.cmake
  • CMAKE_PREFIX_PATH should point to your WebAssembly libraries directory (e.g., $WASM_LIBS)

Verify Dependencies​

Ensure all required dependencies are installed:

# Check versions
cmake --version      # Should be 3.24+
git --version
g++ --version        # Should be 13+ on Ubuntu

# For native builds
ls /usr/local/include/dawn  # Should exist

# For web builds
emcc --version
em++ --version

# For web builds - check WebAssembly libraries
ls $WASM_LIBS/lib/libboost_iostreams.a
ls $WASM_LIBS/lib/libgmp.a
ls $WASM_LIBS/lib/libssl.a

Getting Help​

If you encounter issues not covered here:

  1. Review documentation: Check the Installation and Building Dependencies guides
  2. Check existing issues: Visit GitHub Issues
  3. Join Telegram: Telegram Community
  4. Follow updates: @ligero_inc on X

When reporting issues, include:

  • Operating system and version
  • GPU model and driver version
  • Ligetron version (git commit hash)
  • Complete error message
  • Minimal reproduction steps
  • CMake command used
  • Environment variables (especially CPATH, PATH, CMAKE_PREFIX_PATH)