Skip to main content

Troubleshooting

Common issues and solutions when using Wasmrun.

Plugin Issues​

Plugin Not Available​

Problem: Error message "Plugin not available" when running a project.

Solution:

For built-in language support:

# C/C++ is built-in, no installation needed
wasmrun --language c ./my-project

For external plugins, install them first:

# Install the appropriate plugin
wasmrun plugin install wasmrust   # Rust plugin
wasmrun plugin install wasmgo     # Go plugin
wasmrun plugin install waspy      # Python plugin
wasmrun plugin install wasmasc    # AssemblyScript plugin

# Verify installation
wasmrun plugin list

Plugin Dependencies Missing​

Problem: Error about missing tools or dependencies.

Solution:

Check which dependencies are needed:

wasmrun plugin info <plugin-name>

Install missing tools:

For Rust (wasmrust plugin):

rustup target add wasm32-unknown-unknown
cargo install wasm-pack  # Optional, for web apps

For Go (wasmgo plugin):

# Install TinyGo from: https://tinygo.org/
# macOS:
brew install tinygo
# Linux: See https://tinygo.org/getting-started/install/

For Python (waspy plugin):

# No dependencies! waspy is a pure Rust compiler

For AssemblyScript (wasmasc plugin):

npm install -g assemblyscript
# or
yarn global add assemblyscript
# or
pnpm add -g assemblyscript

For C/C++ (built-in):

# Install Emscripten from: https://emscripten.org/

Wrong Plugin Selected​

Problem: Wasmrun is using the wrong language plugin for your project.

Solution:

Force a specific plugin:

wasmrun --language rust ./project
wasmrun --language go ./project
wasmrun --language python ./project
wasmrun --language c ./project
wasmrun --language asc ./project

Or ensure your project has proper configuration files:

  • Rust: Cargo.toml
  • Go: go.mod
  • Python: .py files
  • C/C++: Makefile or .c/.cpp files
  • AssemblyScript: package.json with assemblyscript dependency

Plugin Installation Fails​

Problem: wasmrun plugin install command fails.

Solution:

  1. Check internet connection
  2. Verify cargo is installed and updated:
rustup update
cargo --version
  1. Check crates.io is accessible:
cargo search wasmrust
  1. Try with verbose output:
wasmrun --debug plugin install wasmrust
  1. Manually install via cargo:
cargo install wasmrust
# Then check if wasmrun detects it
wasmrun plugin list

Installation Issues​

Cargo Installation Fails​

Problem: cargo install wasmrun fails.

Solution:

  1. Update Rust toolchain:
rustup update stable
  1. Clear cargo cache and retry:
rm -rf ~/.cargo/registry/cache
cargo install wasmrun
  1. Install from source:
git clone https://github.com/anistark/wasmrun.git
cd wasmrun
cargo install --path .

DEB/RPM Package Installation Issues​

Problem: Package installation fails on Linux.

Solution:

For DEB packages:

# Fix dependency issues
sudo apt install -f

# Install manually
sudo dpkg -i wasmrun_*.deb
sudo apt-get install -f

For RPM packages:

# Use dnf (Fedora/RHEL 8+)
sudo dnf install wasmrun-*.rpm

# Or rpm directly
sudo rpm -i wasmrun-*.rpm

# Fix dependencies
sudo dnf install -f

Binary Not Found After Installation​

Problem: wasmrun: command not found after installation.

Solution:

Add cargo bin directory to PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.cargo/bin:$PATH"

# Reload shell config
source ~/.bashrc  # or ~/.zshrc

Verify installation:

which wasmrun
wasmrun --version

Server Issues​

Port Already in Use​

Problem: Error "Address already in use" or port binding fails.

Solution:

Option 1: Stop existing wasmrun server

wasmrun stop

Option 2: Use a different port

wasmrun run ./project --port 3001

Option 3: Find and kill the process using the port

# macOS/Linux
lsof -ti:8420 | xargs kill -9

# Or find the PID manually
lsof -i:8420
kill -9 <PID>

Server Won't Start​

Problem: Development server fails to start.

Solution:

  1. Check port availability:
lsof -i:8420  # Check default port
  1. Try with debug mode:
wasmrun --debug run ./project
  1. Check file permissions:
ls -la ./project
# Ensure you have read permissions
  1. Verify project structure:
# Ensure entry files exist
ls -la ./project/src/

Compilation Issues​

No Entry Point Found​

Problem: Error "No entry point found" when running WASM file.

Solution:

  1. Ensure your WASM has an entry function:

    • main() function
    • _start() function
    • Or use -c/--call to specify a function:
    wasmrun exec file.wasm -c my_function

  2. Inspect your WASM file:

wasmrun inspect file.wasm
# Check for exported functions
  1. Verify compilation output:
wasmrun compile ./project --verbose

Compilation Fails​

Problem: Project won't compile.

Solution:

  1. Check dependencies:
wasmrun plugin info <language>
# Install any missing dependencies
  1. Verify project structure:
# For Rust
cat Cargo.toml
# Check wasm32 target

# For Go
cat go.mod
# Verify TinyGo compatibility

# For C
cat Makefile
# Check Emscripten configuration
  1. Try with verbose output:
wasmrun compile ./project --verbose
  1. Use debug mode:
wasmrun --debug compile ./project

Build Artifacts Not Found​

Problem: Can't find compiled WASM files.

Solution:

Check standard output locations:

For Rust:

ls ./target/wasm32-unknown-unknown/release/*.wasm
ls ./target/wasm32-unknown-unknown/debug/*.wasm

For Go (TinyGo):

ls ./*.wasm
ls ./build/*.wasm

For C (Emscripten):

ls ./build/*.wasm
ls ./*.wasm

Or compile with specified output:

wasmrun compile ./project --output ./build/

Native Execution Issues​

wasm-bindgen Module Detected​

Problem: "wasm-bindgen module detected" error when using wasmrun exec.

Explanation: wasm-bindgen modules require JavaScript runtime features and are not supported in native execution mode.

Solution:

Option 1: Run the project directory (uses dev server):

wasmrun run ./my-rust-project

Option 2: Compile without wasm-bindgen:

// Cargo.toml - remove wasm-bindgen
[dependencies]
# wasm-bindgen = "0.2"  # Remove this

// Use wasm32-wasi target instead
cargo build --target wasm32-wasi
wasmrun exec target/wasm32-wasi/release/my_project.wasm

Option 3: Use Go/TinyGo for CLI tools:

tinygo build -o output.wasm -target wasi main.go
wasmrun exec output.wasm

Native Execution Fails on Rust WASM​

Problem: Rust WASM files fail with native execution.

Explanation: Some Rust functions require panic hooks, stack unwinding, or memory allocators that aren't fully supported in native mode.

Solution:

Recommended approaches:

  1. Run the project directory (dev server):
wasmrun ./my-rust-project
  1. Use wasm32-wasi target for CLI tools:
cargo build --target wasm32-wasi
wasmrun exec target/wasm32-wasi/release/project.wasm
  1. Write pure functions without panic handling:
#[no_mangle]
pub extern "C" fn add(a: i32, b: i32) -> i32 {
    a + b  // Simple, no panic possible
}

Workarounds:

  • Avoid functions that can panic
  • Use #[no_mangle] for exported functions
  • Keep functions simple and pure
  • Prefer Go/TinyGo for complex CLI tools

Function Execution Fails​

Problem: Specific function fails during native execution.

Solution:

  1. Check function signature:
wasmrun inspect file.wasm
# Verify function is exported
  1. Try with explicit function call:
wasmrun exec file.wasm -c function_name arg1 arg2
  1. Check for language-specific issues:

Rust: May need panic hooks or runtime

// Use simpler, pure functions
#[no_mangle]
pub extern "C" fn simple_fn(x: i32) -> i32 {
    x * 2
}

Go/TinyGo: May need scheduler initialization

# Use -scheduler=none for simple functions
tinygo build -o out.wasm -scheduler=none main.go

File Watching Issues​

Live Reload Not Working​

Problem: Changes don't trigger recompilation with --watch.

Solution:

  1. Ensure --watch flag is used:
wasmrun run ./project --watch
  1. Check file permissions:
ls -la ./project/src/
  1. Verify supported file types are being changed:
  • .rs for Rust
  • .go for Go
  • .py for Python
  • .c, .cpp for C/C++
  • .ts for AssemblyScript
  1. Try restarting the server:
wasmrun stop
wasmrun run ./project --watch

Too Many Open Files​

Problem: "Too many open files" error with file watching.

Solution:

Increase file descriptor limit:

macOS:

ulimit -n 4096

Linux:

ulimit -n 4096
# Or permanently in /etc/security/limits.conf

Debugging Tips​

Enable Debug Mode​

Get detailed information about what's happening:

# Any command with debug output
wasmrun --debug run ./project
wasmrun --debug compile ./project
wasmrun --debug plugin install wasmrust

# Save debug output to file
wasmrun --debug compile ./project 2> debug.log

Get Plugin Information​

# List all plugins
wasmrun plugin list

# Get detailed plugin info
wasmrun plugin info wasmrust
wasmrun plugin info wasmgo

# Check plugin installation location
ls -la ~/.wasmrun/plugins/

Verify WASM File​

# Basic verification
wasmrun verify file.wasm

# Detailed analysis
wasmrun verify file.wasm --detailed

# Inspect structure
wasmrun inspect file.wasm

Check System Information​

# Wasmrun version
wasmrun --version

# Rust version
rustc --version
cargo --version

# Check PATH
echo $PATH | tr ':' '\n'

# Check cargo bin directory
ls -la ~/.cargo/bin/

Getting Help​

If you're still experiencing issues:

  1. Check existing issues: GitHub Issues
  2. Enable debug mode: Run with --debug flag
  3. Gather information:
    • OS and version
    • Rust version (rustc --version)
    • Wasmrun version (wasmrun --version)
    • Plugin list (wasmrun plugin list)
    • Error messages (full output)
  4. Create an issue: New Issue

Include in your issue:

  • Full error message
  • Debug output (if applicable)
  • Steps to reproduce
  • System information
  • Project structure (if relevant)
  • Screenshots (if applicable)

Common Error Messages​

"Plugin not available"​

See Plugin Not Available

"Plugin dependencies missing"​

See Plugin Dependencies Missing

"Port already in use"​

See Port Already in Use

"No entry point found"​

See No Entry Point Found

"wasm-bindgen module detected"​

See wasm-bindgen Module Detected

"Address already in use"​

See Port Already in Use

"Too many open files"​

See Too Many Open Files

Next Steps​