Troubleshooting Guide

Common problems and solutions when working with Neuro.

Installation Issues

"No suitable version of LLVM was found"

Symptoms:

Cause: LLVM_SYS_201_PREFIX not set or points to wrong location. Neuro requires LLVM 20.

Solution:

Windows:

1# Set environment variable (adjust path to your LLVM 20 install)2[System.Environment]::SetEnvironmentVariable('LLVM_SYS_201_PREFIX', 'C:\LLVM-20', 'Machine')3 4# Restart terminal and verify5$env:LLVM_SYS_201_PREFIX

Unix:

# Add to ~/.bashrc or ~/.zshrc (path varies by distro)
export LLVM_SYS_201_PREFIX=/usr/lib/llvm-20   # Ubuntu/Debian
# export LLVM_SYS_201_PREFIX=/usr/lib/llvm20  # Arch/CachyOS

# Reload shell config
source ~/.bashrc

# Verify
echo $LLVM_SYS_201_PREFIX

"LLVMConfig.cmake not found"

Symptoms:

Cause: Installed .exe installer instead of full development package.

Solution:

Download and extract the full development package:

• Windows: the LLVM 20 clang+llvm-20.*-x86_64-pc-windows-msvc.tar.xz archive
• URL: https://github.com/llvm/llvm-project/releases

DO NOT use the .exe installer - it lacks required development files.

"cannot open input file 'libxml2s.lib'" (Windows)

Symptoms:

Cause: libxml2 not installed via vcpkg.

Solution:

1cd C:\vcpkg2.\vcpkg install libxml2:x64-windows-static3.\vcpkg integrate install4 5# Verify installation6.\vcpkg list | findstr libxml2

Build fails with linker errors (Unix)

Symptoms:

Cause: Missing C/C++ compiler toolchain.

Solution:

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install build-essential

Arch:

sudo pacman -S base-devel

macOS:

xcode-select --install

cargo build --features mlir fails

The mlir-backend slice's mlir feature is opt-in and needs more than stock LLVM 20. Default builds compile a placeholder and need none of this.

Symptoms:

Cause: two separate gaps.

1. Most distro LLVM 20 packages (Arch/CachyOS llvm20 included) ship no MLIR — no mlir-c headers, no libMLIR*. Check with ls $LLVM_SYS_201_PREFIX/include/mlir-c.
2. mlir-sys runs bindgen over the MLIR-C headers. A newer libclang than 20 misparses LLVM 20's DEFINE_C_API_STRUCT macro, yielding opaque 1-byte structs and the 0_usize - 8_usize const-eval underflow above. Rolling distros ship libclang 22.

Solution: build LLVM 20 with MLIR enabled, and point bindgen at a libclang 20.

# 1. LLVM 20 + MLIR, installed to a prefix of your choosing
cmake -S llvm -B build -DLLVM_ENABLE_PROJECTS=mlir -DCMAKE_INSTALL_PREFIX=<mlir-prefix> ...

# 2. libclang 20, unpacked anywhere (no system downgrade needed)
#    needs libclang.so* plus the clang/20/include resource headers

# 3. Point every binding at them
export LLVM_SYS_201_PREFIX=<mlir-prefix>   # inkwell
export MLIR_SYS_200_PREFIX=<mlir-prefix>   # melior
export TABLEGEN_200_PREFIX=<mlir-prefix>   # mlir-tblgen
export LIBCLANG_PATH=<libclang-20-dir>
export BINDGEN_EXTRA_CLANG_ARGS="-resource-dir=<libclang-20-dir>/clang/20"

cargo test -p mlir-backend --features mlir

If the distro libclang 20 is linked against the distro's own versioned libLLVM.so.20.1, put that package's lib/ first on LD_LIBRARY_PATH so bindgen can load it, and the MLIR prefix's lib/ second for the runtime libMLIR.

Compilation Errors

Type Mismatch Errors

Symptoms:

Causes:

1. Incorrect type in assignment or return
2. Mixing integer and float types
3. Using wrong type for function argument

Solutions:

Check variable types:

1// Error: mixing types2val x: i32 = 103val y: f64 = 3.144// val z = x + y  // Type mismatch5 6// Fix: use same types7val x: f64 = 10.08val y: f64 = 3.149val z: f64 = x + y  // OK

Check function signatures:

1func takes_i32(x: i32) -> i32 {2    return x3}4 5// Error: passing wrong type6val y: f64 = 3.147// takes_i32(y)  // Type mismatch8 9// Fix: use correct type10val x: i32 = 4211takes_i32(x)  // OK

Undefined Variable Errors

Symptoms:

Causes:

1. Variable not declared before use
2. Typo in variable name
3. Variable out of scope

Solutions:

Declare before use:

1// Error: undefined2// return x3 4// Fix: declare first5val x: i32 = 426return x

Check scope:

1func scoped() -> i32 {2    if true {3        val x: i32 = 104    }5    // return x  // Error: x out of scope6 7    // Fix: declare in correct scope8    val x: i32 = 109    if true {10        // x is accessible here11    }12    return x  // OK13}

Cannot Assign to Immutable Variable

Symptoms:

Cause: Trying to reassign val variable.

Solution:

Use mut for variables that need to change:

1// Error: immutable2val x: i32 = 103// x = 20  // Error4 5// Fix: use mut6mut y: i32 = 107y = 20  // OK

Missing Return Statement

Symptoms:

Cause: Function doesn't return a value on all code paths.

Solutions:

Add missing return:

1// Error: missing return for x <= 02func bad(x: i32) -> i32 {3    if x > 0 {4        return x5    }6    // Missing return for else case7}8 9// Fix: add else branch10func good(x: i32) -> i32 {11    if x > 0 {12        return x13    } else {14        return 015    }16}

Use implicit return:

1func good_implicit(x: i32) -> i32 {2    if x > 0 {3        x4    } else {5        06    }7}

Parse Errors

Symptoms:

Parse errors stop the run at the first one; only the type checker reports a list.

Common causes:

1. A stray semicolon (Neuro has none, see below)
2. Unbalanced brackets/braces
3. Syntax errors

Solutions:

Remove semicolons: Neuro statements are terminated by a newline, not ;. A trailing semicolon is an unexpected token Semicolon parse error:

1// Error: semicolons are not valid tokens2val x: i32 = 10;3val y: i32 = 20;4 5// Fix: one statement per line, no `;`6val x: i32 = 107val y: i32 = 20

Check brackets:

1// Error: unbalanced braces2func bad() -> i32 {3    if true {4        return 15    // Missing closing brace6}7 8// Fix: add missing brace9func good() -> i32 {10    if true {11        return 112    }  // Closing brace added13}

Runtime Issues

Executable Doesn't Run (Windows)

Symptoms:

• Executable created but won't run
• "Cannot find DLL" errors

Causes:

1. Missing MSVC runtime
2. Antivirus blocking execution

Solutions:

Install Visual C++ Redistributable:

• Download from: https://aka.ms/vs/17/release/vc_redist.x64.exe
• Install and restart

Check antivirus:

• Add exception for Neuro executables
• Temporarily disable to test

Permission Denied (Unix)

Symptoms:

Cause: Executable permission not set.

Solution:

chmod +x ./program
./program

Runtime Crash (signal)

Symptoms: The compiled program dies on an OS signal instead of exiting normally.

Causes (rare):

1. Division by zero raises a hardware exception (SIGFPE); there is no checked division yet
2. Integer overflow with -O0 traps deliberately (the overflow check aborts the process); release builds wrap silently
3. A compiler bug (codegen producing invalid memory accesses)

Solutions:

Check for division by zero:

1// Potential crash2val x: i32 = 10 / 0  // Division by zero3 4// Fix: check denominator5func safe_divide(a: i32, b: i32) -> i32 {6    if b == 0 {7        return 0  // Or handle error8    } else {9        return a / b10    }11}

Report compiler bugs:

• GitHub Issues: https://github.com/PanzerPeter/Neuro/issues
• Include minimal reproduction case

Performance Issues

Slow Compilation

Symptoms: Compilation takes longer than expected.

Causes:

1. Debug build of compiler
2. Large program
3. System resource constraints

Solutions:

Use release build:

# Build compiler in release mode
cargo build --release -p neurc

# Use release build
cargo run --release -p neurc -- compile program.nr

Check system resources:

• Close unnecessary applications
• Ensure sufficient RAM (minimum 4GB recommended)
• Check disk space

Large Executable Size

Symptoms: Executable is larger than expected.

Causes:

1. Debug information included
2. Lower optimization level selected for faster compile time

Solutions:

Current:

• Use -O2 or -O3 during neurc compile to reduce binary size and improve runtime performance
• Typical size: 1-5 MB for simple programs

Further optimization options:

• Strip debug info with linker options

Development Environment Issues

VSCode Syntax Highlighting Not Working

Symptoms: .nr files show no syntax highlighting.

Solution:

Install Neuro VSCode extension:

cd neuro-language-support
npm install -g @vscode/vsce
vsce package
code --install-extension neuro-language-support-*.vsix --force

Then reload the window (Developer: Reload Window). Highlighting in an editor that was already open does not refresh on its own.

Git Line Ending Issues (Windows)

Symptoms: Git shows all files as modified.

Solution:

# Configure Git for cross-platform development
git config --global core.autocrlf true

Debugging Techniques

Enable Debug Logging

Get detailed compilation information:

# Windows (PowerShell)
$env:RUST_LOG="debug"
neurc compile program.nr 2> debug.log

# Unix
RUST_LOG=debug neurc compile program.nr 2> debug.log

# Review log
cat debug.log

Isolate the Problem

Create minimal reproduction:

1// Start with simplest program2func main() -> i32 {3    return 04}5 6// Gradually add code until error appears

Check Each Stage

Test compilation stages separately:

# 1. Check syntax only
neurc check program.nr

# 2. If check passes, try compile
neurc compile program.nr

# 3. If compile passes, try run
./program

Getting Help

Before Asking for Help

1. Check this troubleshooting guide
2. Search GitHub issues
3. Enable debug logging
4. Create minimal reproduction
5. Review CONTRIBUTING.md for development and reporting guidelines

Reporting Issues

Include in bug reports:

• Neuro compiler version
• Operating system and version
• LLVM version
• Rust version
• Complete error message
• Minimal reproduction case
• Steps to reproduce

Template:

1## Environment2- OS: Windows 11 / Ubuntu 22.04 / macOS 133- Neuro: version from `neurc --version` (and commit hash)4- LLVM: 20.x5- Rust: 1.85+6 7## Issue8[Description]9 10## Reproduction11[Minimal .nr file that reproduces the issue]12 13## Expected14[What should happen]15 16## Actual17[What actually happens]18 19## Error Output

[Complete error message with debug logging]

Resources

• GitHub Issues: https://github.com/PanzerPeter/Neuro/issues
• Documentation: README.md
• Development Guidelines: CONTRIBUTING.md

Known Limitations (current)

These are not bugs, but current limitations. See the Quick Roadmap for what is landed and what is planned.

1. Type inference: bare numeric literals default to i32 / f64 unless a type is in scope
2. Generic type arguments: restricted to Copy types, and a generic may not be instantiated with an enclosing type parameter (no Option<T> inside a func f<T>)
3. Strings are immutable: +, .len(), .clone(), .slice(a..b), .char_slice(a..b), .chars(), .char_indices(). Build text that grows with the String buffer (String::new / .push_str / .clear / .to_string) instead of chaining +
4. String interpolation holes: a hole may not contain a " string literal, and an interpolated literal is not a constant pattern. Triple-quoted """ blocks and nesting block comments carry no such restriction
5. Ranges: a..b and a..=b drive for loops and .slice(); .rev() and .step(n) are not implemented yet
6. Optimization: -O0 through -O3 supported (higher levels may increase compile time)

Planned features are tracked through project issues and changelog updates.

Common Warnings

The compiler currently emits one lint:

prefer-loop-over-while-true

Message:

Cause: A while loop whose condition is the literal true. loop { ... } says the same thing and is the idiomatic form.

Solution:

1// Triggers the lint2while true {3    break4}5 6// Preferred7loop {8    break9}

Silence it with @allow(prefer_loop_over_while_true) on the enclosing function when the literal form reads better. Warnings never block compilation.

FAQ

Why does my program compile but do nothing?

Check that main returns the expected exit code and performs desired operations.

Why can't I mix i32 and i64?

Neuro uses strict typing with no implicit conversions. Convert explicitly with an as cast: val wide: i64 = narrow as i64.

Why is compilation slow?

Use -O0 for fastest compile/debug loops and -O2/-O3 for faster runtime binaries.

How do I speed up development?

Use neurc check for rapid feedback without code generation.

Can I use Neuro for production?

Not yet — the language is alpha. The core language (Phase 1) is complete and tensor values can be built, but tensor arithmetic, autodiff, and the GPU path are still ahead; see the Quick Roadmap.

Still Stuck?

If this guide doesn't solve your problem:

1. Check CLI Usage Guide
2. Review Language Reference
3. Search or create GitHub Issue
4. Include all requested information in bug reports