Troubleshooting Guide

Common problems and solutions when working with Neuro.

Installation Issues

"No suitable version of LLVM was found"

Symptoms:

text

1error: No suitable version of LLVM was found system-wide or pointed2       to by LLVM_SYS_231_PREFIX.

Cause: LLVM_SYS_231_PREFIX not set or points to wrong location. Neuro requires LLVM 23.

Solution:

Windows:

powershell

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

Unix:

shell

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

# Reload shell config
source ~/.bashrc

# Verify
echo $LLVM_SYS_231_PREFIX

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

# Reload shell config
source ~/.bashrc

# Verify
echo $LLVM_SYS_231_PREFIX

"LLVMConfig.cmake not found"

Symptoms:

text

1Could not find LLVMConfig.cmake

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

Solution:

Download and extract the full development package:

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

Do not use the .exe installer: it lacks the development files.

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

Symptoms:

text

1LINK : fatal error LNK1181: cannot open input file 'xml2s.lib'

Cause: LLVM's llvm-config.exe --system-libs names xml2s.lib, because LLVM's Windows manifest merger uses libxml2. Nothing Neuro calls reaches it, so no libxml2 code is linked, but the linker still stops when a named library is missing.

Solution: copy any static libxml2 into the LLVM lib directory under that name:

powershell

1vcpkg install "libxml2[core]:x64-windows-static"2Get-ChildItem "<vcpkg-root>\installed\x64-windows-static\lib\*xml2*.lib" |3  Select-Object -First 1 | Copy-Item -Destination "$env:LLVM_SYS_231_PREFIX\lib\xml2s.lib"

Build fails with linker errors (Unix)

Symptoms:

text

1error: linker `cc` not found

Cause: Missing C/C++ compiler toolchain.

Solution:

Ubuntu/Debian:

shell

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

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

Arch:

shell

sudo pacman -S base-devel

sudo pacman -S base-devel

macOS:

shell

xcode-select --install

xcode-select --install

`mlir-sys` fails to build

Every build compiles the mlir-backend slice, which needs MLIR 23 on top of LLVM 23.

Symptoms:

text

1failed to run `".../bin/llvm-config" ...`2# or3fatal error: 'mlir-c/IR.h' file not found4# or, at link time5unable to find library -lMLIR-C

Cause: mlir-sys finds MLIR by running $MLIR_SYS_230_PREFIX/bin/llvm-config and reading its lib/ and include/. MLIR has to live in the same prefix as that llvm-config, and a prefix with no static LLVM libraries makes mlir-sys link the shared MLIR-C library, which distro packages (Arch's aur/mlir included) do not build.

Solution: use a prefix that holds LLVM and MLIR together: apt.llvm.org's /usr/lib/llvm-23 with libmlir-23-dev installed, Homebrew's llvm, or a source build of LLVM 23 with -DLLVM_ENABLE_PROJECTS=mlir. Point all three variables at it. See Installation → MLIR.

shell

export LLVM_SYS_231_PREFIX=<prefix>   # inkwell
export MLIR_SYS_230_PREFIX=<prefix>   # melior
export TABLEGEN_230_PREFIX=<prefix>   # melior's TableGen macros
cargo test -p mlir-backend

export LLVM_SYS_231_PREFIX=<prefix>   # inkwell
export MLIR_SYS_230_PREFIX=<prefix>   # melior
export TABLEGEN_230_PREFIX=<prefix>   # melior's TableGen macros
cargo test -p mlir-backend

If bindgen reports opaque 1-byte structs (attempt to compute 0_usize - 8_usize), the libclang it loaded is a different major version from the MLIR headers. Point LIBCLANG_PATH at a libclang 23.

Compilation Errors

Type Mismatch Errors

Symptoms:

text

1Type errors found in "program.nr":2error: type mismatch: expected i32, found f643 --> program.nr:2:54  |52 |     val x: i32 = 3.146  |     ^^^^^^^^^^^^^^^^^7 8Error: 1 type error(s) found

Causes:

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

Solutions:

Check variable types:

neuro

// Error: mixing types
val x: i32 = 10
val y: f64 = 3.14
// val z = x + y  // Type mismatch

// Fix: use same types
val x: f64 = 10.0
val y: f64 = 3.14
val z: f64 = x + y  // OK

// Error: mixing types
val x: i32 = 10
val y: f64 = 3.14
// val z = x + y  // Type mismatch

// Fix: use same types
val x: f64 = 10.0
val y: f64 = 3.14
val z: f64 = x + y  // OK

Check function signatures:

neuro

func takes_i32(x: i32) -> i32 {
    return x
}

// Error: passing wrong type
val y: f64 = 3.14
// takes_i32(y)  // Type mismatch

// Fix: use correct type
val x: i32 = 42
takes_i32(x)  // OK

func takes_i32(x: i32) -> i32 {
    return x
}

// Error: passing wrong type
val y: f64 = 3.14
// takes_i32(y)  // Type mismatch

// Fix: use correct type
val x: i32 = 42
takes_i32(x)  // OK

Undefined Variable Errors

Symptoms:

text

1Type errors found in "program.nr":2error: undefined variable 'z'3 --> program.nr:2:144  |52 |     return z + 16  |            ^7 8Error: 1 type error(s) found

Causes:

Variable not declared before use
Typo in variable name
Variable out of scope

Solutions:

Declare before use:

neuro

// Error: undefined
// return x

// Fix: declare first
val x: i32 = 42
return x

// Error: undefined
// return x

// Fix: declare first
val x: i32 = 42
return x

Check scope:

neuro

func scoped() -> i32 {
    if true {
        val x: i32 = 10
    }
    // return x  // Error: x out of scope

    // Fix: declare in correct scope
    val x: i32 = 10
    if true {
        // x is accessible here
    }
    return x  // OK
}

func scoped() -> i32 {
    if true {
        val x: i32 = 10
    }
    // return x  // Error: x out of scope

    // Fix: declare in correct scope
    val x: i32 = 10
    if true {
        // x is accessible here
    }
    return x  // OK
}

Cannot Assign to Immutable Variable

Symptoms:

text

1Type errors found in "program.nr":2error: cannot assign to immutable variable 'x'3 --> program.nr:3:54  |53 |     x = 206  |     ^^^^^^7 8Error: 1 type error(s) found

Cause: Trying to reassign val variable.

Solution:

Use mut for variables that need to change:

neuro

// Error: immutable
val x: i32 = 10
// x = 20  // Error

// Fix: use mut
mut y: i32 = 10
y = 20  // OK

// Error: immutable
val x: i32 = 10
// x = 20  // Error

// Fix: use mut
mut y: i32 = 10
y = 20  // OK

Missing Return Statement

Symptoms:

text

1Type errors found in "program.nr":2error: missing return statement in function returning i323 --> program.nr:1:14  |51 | func compute(x: i32) -> i32 {6  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^7 8Error: 1 type error(s) found

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

Solutions:

Add missing return:

neuro

// Error: missing return for x <= 0
func bad(x: i32) -> i32 {
    if x > 0 {
        return x
    }
    // Missing return for else case
}

// Fix: add else branch
func good(x: i32) -> i32 {
    if x > 0 {
        return x
    } else {
        return 0
    }
}

// Error: missing return for x <= 0
func bad(x: i32) -> i32 {
    if x > 0 {
        return x
    }
    // Missing return for else case
}

// Fix: add else branch
func good(x: i32) -> i32 {
    if x > 0 {
        return x
    } else {
        return 0
    }
}

Use implicit return:

neuro

func good_implicit(x: i32) -> i32 {
    if x > 0 {
        x
    } else {
        0
    }
}

func good_implicit(x: i32) -> i32 {
    if x > 0 {
        x
    } else {
        0
    }
}

Parse Errors

Symptoms:

text

1error: unexpected token RightBrace, expected expression2 --> program.nr:3:13  |43 | }5  | ^6 7Error: Parsing failed

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

Common causes:

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

Solutions:

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

neuro

// Error: semicolons are not valid tokens
val x: i32 = 10;
val y: i32 = 20;

// Fix: one statement per line, no `;`
val x: i32 = 10
val y: i32 = 20

// Error: semicolons are not valid tokens
val x: i32 = 10;
val y: i32 = 20;

// Fix: one statement per line, no `;`
val x: i32 = 10
val y: i32 = 20

Check brackets:

neuro

// Error: unbalanced braces
func bad() -> i32 {
    if true {
        return 1
    // Missing closing brace
}

// Fix: add missing brace
func good() -> i32 {
    if true {
        return 1
    }  // Closing brace added
}

// Error: unbalanced braces
func bad() -> i32 {
    if true {
        return 1
    // Missing closing brace
}

// Fix: add missing brace
func good() -> i32 {
    if true {
        return 1
    }  // Closing brace added
}

Runtime Issues

Executable Doesn't Run (Windows)

Symptoms:

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

Causes:

Missing MSVC runtime
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:

text

1bash: ./program: Permission denied

Cause: Executable permission not set.

Solution:

shell

chmod +x ./program
./program

chmod +x ./program
./program

Runtime Panic

Symptoms: The program prints a panic: line naming a source position, then aborts (SIGABRT, which a shell reports as status 134; neurc run reports it as status 1):

text

1panic: division by zero at program.nr:1:33

Causes:

Integer division or remainder by zero. The divisor is checked at every optimization level.
Integer overflow in a build at -O0, reported as panic: integer overflow. From -O1 up, arithmetic wraps silently.
An explicit panic(msg), a failed assert(cond), or a reached unreachable().

Solutions:

Check the divisor:

neuro

func safe_divide(a: i32, b: i32) -> i32 {
    if b == 0 {
        return 0  // or report the failure through an Option or Result
    }
    return a / b
}

func safe_divide(a: i32, b: i32) -> i32 {
    if b == 0 {
        return 0  // or report the failure through an Option or Result
    }
    return a / b
}

For overflow, .checked_add, .checked_sub and .checked_mul return an Option instead of panicking; see integer methods.

Runtime Crash (signal)

A program that dies on a signal (SIGSEGV, SIGILL) rather than a panic: line has hit either unbounded recursion or a compiler bug. Report it with a minimal reproduction:

GitHub Issues: https://github.com/PanzerPeter/Neuro/issues

Performance Issues

Slow Compilation

Symptoms: Compilation takes longer than expected.

Causes:

Debug build of compiler
Large program
System resource constraints

Solutions:

Use release build:

shell

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

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

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

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

Development Environment Issues

VSCode Syntax Highlighting Not Working

Symptoms: .nr files show no syntax highlighting.

Solution:

Install the extension from neuro-language-support/ as described in Editor Support, then reload the window (Developer: Reload Window). An editor that was already open does not pick up a new grammar on its own.

Git Line Ending Issues (Windows)

Symptoms: Git shows all files as modified.

Solution:

shell

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

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

Debugging Techniques

Enable Debug Logging

Get detailed compilation information:

shell

# 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

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

neuro

// Start with simplest program
func main() -> i32 {
    return 0
}

// Gradually add code until error appears

// Start with simplest program
func main() -> i32 {
    return 0
}

// Gradually add code until error appears

Check Each Stage

Test compilation stages separately:

shell

# 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

# 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

Check this troubleshooting guide
Search GitHub issues
Enable debug logging
Create minimal reproduction
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:

markdown

1## Environment2- OS: Windows 11 / Ubuntu 22.04 / macOS 133- Neuro: version from `neurc --version` (and commit hash)4- LLVM: 23.x5- Rust: 1.98.1+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 Output20```text21[Complete error message with debug logging]22```

Resources

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

Known Limitations

Features that are planned but not built yet are on the Quick Roadmap. Each language reference page states the limits of the feature it covers. The one that surprises people most often: an interpolation hole cannot contain a string literal. "{"lit"}" is a lexical error; bind the string to a name first and interpolate the name.

Common Warnings

The compiler currently emits two warnings. Warnings never block compilation.

`prefer-loop-over-while-true`

Message:

text

1warning[prefer-loop-over-while-true] at 24..28: `while true { ... }` should be written as `loop { ... }`; silence with `@allow(prefer_loop_over_while_true)` on the enclosing function

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

Solution:

neuro

// Triggers the lint
while true {
    break
}

// Preferred
loop {
    break
}

// Triggers the lint
while true {
    break
}

// Preferred
loop {
    break
}

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

`float-cast-out-of-range`

Message:

text

1warning[float-cast-out-of-range] at 42..53: constant `1e20` does not fit `i32` and saturates to its maximum; use `.to_checked::<i32>()` for an `Option`, or silence with `@allow(float_cast_out_of_range)` on the enclosing function or `const`

Cause: An as cast from a float to an integer type whose operand is a constant the target cannot hold, or NaN. The cast clamps it to the type's minimum or maximum (NaN becomes 0), which is rarely the value the author meant.

Solution: Fix the constant or widen the target type. Where the program computes the value at run time, .to_checked::<T>() returns None for it instead of clamping. If the clamp is what you want, add @allow(float_cast_out_of_range) to the enclosing function or method, or to the const whose initializer holds the cast.

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, and its syntax and semantics can still change between releases. The Quick Roadmap shows what is complete and what is ahead.

Still Stuck?

If this guide doesn't solve your problem:

Check CLI Usage Guide
Review Language Reference
Search or create GitHub Issue
Include all requested information in bug reports

Troubleshooting Guide

Common problems and solutions when working with Neuro.

Installation Issues

"No suitable version of LLVM was found"

Symptoms:

text

1error: No suitable version of LLVM was found system-wide or pointed2       to by LLVM_SYS_231_PREFIX.

Cause: LLVM_SYS_231_PREFIX not set or points to wrong location. Neuro requires LLVM 23.

Solution:

Windows:

powershell

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

Unix:

shell

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

# Reload shell config
source ~/.bashrc

# Verify
echo $LLVM_SYS_231_PREFIX

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

# Reload shell config
source ~/.bashrc

# Verify
echo $LLVM_SYS_231_PREFIX

"LLVMConfig.cmake not found"

Symptoms:

text

1Could not find LLVMConfig.cmake

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

Solution:

Download and extract the full development package:

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

Do not use the .exe installer: it lacks the development files.

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

Symptoms:

text

1LINK : fatal error LNK1181: cannot open input file 'xml2s.lib'

Solution: copy any static libxml2 into the LLVM lib directory under that name:

powershell

1vcpkg install "libxml2[core]:x64-windows-static"2Get-ChildItem "<vcpkg-root>\installed\x64-windows-static\lib\*xml2*.lib" |3  Select-Object -First 1 | Copy-Item -Destination "$env:LLVM_SYS_231_PREFIX\lib\xml2s.lib"

Build fails with linker errors (Unix)

Symptoms:

text

1error: linker `cc` not found

Cause: Missing C/C++ compiler toolchain.

Solution:

Ubuntu/Debian:

shell

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

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

Arch:

shell

sudo pacman -S base-devel

sudo pacman -S base-devel

macOS:

shell

xcode-select --install

xcode-select --install

`mlir-sys` fails to build

Every build compiles the mlir-backend slice, which needs MLIR 23 on top of LLVM 23.

Symptoms:

text

1failed to run `".../bin/llvm-config" ...`2# or3fatal error: 'mlir-c/IR.h' file not found4# or, at link time5unable to find library -lMLIR-C

shell

export LLVM_SYS_231_PREFIX=<prefix>   # inkwell
export MLIR_SYS_230_PREFIX=<prefix>   # melior
export TABLEGEN_230_PREFIX=<prefix>   # melior's TableGen macros
cargo test -p mlir-backend

export LLVM_SYS_231_PREFIX=<prefix>   # inkwell
export MLIR_SYS_230_PREFIX=<prefix>   # melior
export TABLEGEN_230_PREFIX=<prefix>   # melior's TableGen macros
cargo test -p mlir-backend

If bindgen reports opaque 1-byte structs (attempt to compute 0_usize - 8_usize), the libclang it loaded is a different major version from the MLIR headers. Point LIBCLANG_PATH at a libclang 23.

Compilation Errors

Type Mismatch Errors

Symptoms:

text

1Type errors found in "program.nr":2error: type mismatch: expected i32, found f643 --> program.nr:2:54  |52 |     val x: i32 = 3.146  |     ^^^^^^^^^^^^^^^^^7 8Error: 1 type error(s) found

Causes:

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

Solutions:

Check variable types:

neuro

// Error: mixing types
val x: i32 = 10
val y: f64 = 3.14
// val z = x + y  // Type mismatch

// Fix: use same types
val x: f64 = 10.0
val y: f64 = 3.14
val z: f64 = x + y  // OK

// Error: mixing types
val x: i32 = 10
val y: f64 = 3.14
// val z = x + y  // Type mismatch

// Fix: use same types
val x: f64 = 10.0
val y: f64 = 3.14
val z: f64 = x + y  // OK

Check function signatures:

neuro

func takes_i32(x: i32) -> i32 {
    return x
}

// Error: passing wrong type
val y: f64 = 3.14
// takes_i32(y)  // Type mismatch

// Fix: use correct type
val x: i32 = 42
takes_i32(x)  // OK

func takes_i32(x: i32) -> i32 {
    return x
}

// Error: passing wrong type
val y: f64 = 3.14
// takes_i32(y)  // Type mismatch

// Fix: use correct type
val x: i32 = 42
takes_i32(x)  // OK

Undefined Variable Errors

Symptoms:

text

1Type errors found in "program.nr":2error: undefined variable 'z'3 --> program.nr:2:144  |52 |     return z + 16  |            ^7 8Error: 1 type error(s) found

Causes:

Variable not declared before use
Typo in variable name
Variable out of scope

Solutions:

Declare before use:

neuro

// Error: undefined
// return x

// Fix: declare first
val x: i32 = 42
return x

// Error: undefined
// return x

// Fix: declare first
val x: i32 = 42
return x

Check scope:

neuro

func scoped() -> i32 {
    if true {
        val x: i32 = 10
    }
    // return x  // Error: x out of scope

    // Fix: declare in correct scope
    val x: i32 = 10
    if true {
        // x is accessible here
    }
    return x  // OK
}

func scoped() -> i32 {
    if true {
        val x: i32 = 10
    }
    // return x  // Error: x out of scope

    // Fix: declare in correct scope
    val x: i32 = 10
    if true {
        // x is accessible here
    }
    return x  // OK
}

Cannot Assign to Immutable Variable

Symptoms:

text

1Type errors found in "program.nr":2error: cannot assign to immutable variable 'x'3 --> program.nr:3:54  |53 |     x = 206  |     ^^^^^^7 8Error: 1 type error(s) found

Cause: Trying to reassign val variable.

Solution:

Use mut for variables that need to change:

neuro

// Error: immutable
val x: i32 = 10
// x = 20  // Error

// Fix: use mut
mut y: i32 = 10
y = 20  // OK

// Error: immutable
val x: i32 = 10
// x = 20  // Error

// Fix: use mut
mut y: i32 = 10
y = 20  // OK

Missing Return Statement

Symptoms:

text

1Type errors found in "program.nr":2error: missing return statement in function returning i323 --> program.nr:1:14  |51 | func compute(x: i32) -> i32 {6  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^7 8Error: 1 type error(s) found

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

Solutions:

Add missing return:

neuro

// Error: missing return for x <= 0
func bad(x: i32) -> i32 {
    if x > 0 {
        return x
    }
    // Missing return for else case
}

// Fix: add else branch
func good(x: i32) -> i32 {
    if x > 0 {
        return x
    } else {
        return 0
    }
}

// Error: missing return for x <= 0
func bad(x: i32) -> i32 {
    if x > 0 {
        return x
    }
    // Missing return for else case
}

// Fix: add else branch
func good(x: i32) -> i32 {
    if x > 0 {
        return x
    } else {
        return 0
    }
}

Use implicit return:

neuro

func good_implicit(x: i32) -> i32 {
    if x > 0 {
        x
    } else {
        0
    }
}

func good_implicit(x: i32) -> i32 {
    if x > 0 {
        x
    } else {
        0
    }
}

Parse Errors

Symptoms:

text

1error: unexpected token RightBrace, expected expression2 --> program.nr:3:13  |43 | }5  | ^6 7Error: Parsing failed

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

Common causes:

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

Solutions:

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

neuro

// Error: semicolons are not valid tokens
val x: i32 = 10;
val y: i32 = 20;

// Fix: one statement per line, no `;`
val x: i32 = 10
val y: i32 = 20

// Error: semicolons are not valid tokens
val x: i32 = 10;
val y: i32 = 20;

// Fix: one statement per line, no `;`
val x: i32 = 10
val y: i32 = 20

Check brackets:

neuro

// Error: unbalanced braces
func bad() -> i32 {
    if true {
        return 1
    // Missing closing brace
}

// Fix: add missing brace
func good() -> i32 {
    if true {
        return 1
    }  // Closing brace added
}

// Error: unbalanced braces
func bad() -> i32 {
    if true {
        return 1
    // Missing closing brace
}

// Fix: add missing brace
func good() -> i32 {
    if true {
        return 1
    }  // Closing brace added
}

Runtime Issues

Executable Doesn't Run (Windows)

Symptoms:

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

Causes:

Missing MSVC runtime
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:

text

1bash: ./program: Permission denied

Cause: Executable permission not set.

Solution:

shell

chmod +x ./program
./program

chmod +x ./program
./program

Runtime Panic

Symptoms: The program prints a panic: line naming a source position, then aborts (SIGABRT, which a shell reports as status 134; neurc run reports it as status 1):

text

1panic: division by zero at program.nr:1:33

Causes:

Integer division or remainder by zero. The divisor is checked at every optimization level.
Integer overflow in a build at -O0, reported as panic: integer overflow. From -O1 up, arithmetic wraps silently.
An explicit panic(msg), a failed assert(cond), or a reached unreachable().

Solutions:

Check the divisor:

neuro

func safe_divide(a: i32, b: i32) -> i32 {
    if b == 0 {
        return 0  // or report the failure through an Option or Result
    }
    return a / b
}

func safe_divide(a: i32, b: i32) -> i32 {
    if b == 0 {
        return 0  // or report the failure through an Option or Result
    }
    return a / b
}

For overflow, .checked_add, .checked_sub and .checked_mul return an Option instead of panicking; see integer methods.

Runtime Crash (signal)

A program that dies on a signal (SIGSEGV, SIGILL) rather than a panic: line has hit either unbounded recursion or a compiler bug. Report it with a minimal reproduction:

GitHub Issues: https://github.com/PanzerPeter/Neuro/issues

Performance Issues

Slow Compilation

Symptoms: Compilation takes longer than expected.

Causes:

Debug build of compiler
Large program
System resource constraints

Solutions:

Use release build:

shell

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

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

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

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

Development Environment Issues

VSCode Syntax Highlighting Not Working

Symptoms: .nr files show no syntax highlighting.

Solution:

Git Line Ending Issues (Windows)

Symptoms: Git shows all files as modified.

Solution:

shell

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

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

Debugging Techniques

Enable Debug Logging

Get detailed compilation information:

shell

# 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

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

neuro

// Start with simplest program
func main() -> i32 {
    return 0
}

// Gradually add code until error appears

// Start with simplest program
func main() -> i32 {
    return 0
}

// Gradually add code until error appears

Check Each Stage

Test compilation stages separately:

shell

# 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

# 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

Check this troubleshooting guide
Search GitHub issues
Enable debug logging
Create minimal reproduction
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:

markdown

1## Environment2- OS: Windows 11 / Ubuntu 22.04 / macOS 133- Neuro: version from `neurc --version` (and commit hash)4- LLVM: 23.x5- Rust: 1.98.1+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 Output20```text21[Complete error message with debug logging]22```

Resources

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

Known Limitations

Common Warnings

The compiler currently emits two warnings. Warnings never block compilation.

`prefer-loop-over-while-true`

Message:

text

1warning[prefer-loop-over-while-true] at 24..28: `while true { ... }` should be written as `loop { ... }`; silence with `@allow(prefer_loop_over_while_true)` on the enclosing function

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

Solution:

neuro

// Triggers the lint
while true {
    break
}

// Preferred
loop {
    break
}

// Triggers the lint
while true {
    break
}

// Preferred
loop {
    break
}

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

`float-cast-out-of-range`

Message:

text

1warning[float-cast-out-of-range] at 42..53: constant `1e20` does not fit `i32` and saturates to its maximum; use `.to_checked::<i32>()` for an `Option`, or silence with `@allow(float_cast_out_of_range)` on the enclosing function or `const`

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, and its syntax and semantics can still change between releases. The Quick Roadmap shows what is complete and what is ahead.

Still Stuck?

If this guide doesn't solve your problem:

Check CLI Usage Guide
Review Language Reference
Search or create GitHub Issue
Include all requested information in bug reports

Troubleshooting Guide

Installation Issues

"No suitable version of LLVM was found"

"LLVMConfig.cmake not found"

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

Build fails with linker errors (Unix)

mlir-sys fails to build

Compilation Errors

Type Mismatch Errors

Undefined Variable Errors

Cannot Assign to Immutable Variable

Missing Return Statement

Parse Errors

Runtime Issues

Executable Doesn't Run (Windows)

Permission Denied (Unix)

Runtime Panic

Runtime Crash (signal)

Performance Issues

Slow Compilation

Development Environment Issues

VSCode Syntax Highlighting Not Working

Git Line Ending Issues (Windows)

Debugging Techniques

Enable Debug Logging

Isolate the Problem

Check Each Stage

Getting Help

Before Asking for Help

Reporting Issues

Resources

Known Limitations

Common Warnings

prefer-loop-over-while-true

float-cast-out-of-range

FAQ

Why does my program compile but do nothing?

Why can't I mix i32 and i64?

Why is compilation slow?

How do I speed up development?

Can I use Neuro for production?

Still Stuck?

Troubleshooting Guide

Installation Issues

"No suitable version of LLVM was found"

"LLVMConfig.cmake not found"

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

Build fails with linker errors (Unix)

mlir-sys fails to build

Compilation Errors

Type Mismatch Errors

Undefined Variable Errors

Cannot Assign to Immutable Variable

Missing Return Statement

Parse Errors

Runtime Issues

Executable Doesn't Run (Windows)

Permission Denied (Unix)

Runtime Panic

Runtime Crash (signal)

Performance Issues

Slow Compilation

Development Environment Issues

VSCode Syntax Highlighting Not Working

Git Line Ending Issues (Windows)

Debugging Techniques

Enable Debug Logging

Isolate the Problem

Check Each Stage

Getting Help

Before Asking for Help

Reporting Issues

Resources

Known Limitations

Common Warnings

prefer-loop-over-while-true

float-cast-out-of-range

FAQ

Why does my program compile but do nothing?

Why can't I mix i32 and i64?

`mlir-sys` fails to build

`prefer-loop-over-while-true`

`float-cast-out-of-range`

`mlir-sys` fails to build

`prefer-loop-over-while-true`

`float-cast-out-of-range`