FerrisScript Troubleshooting Guide

Last Updated: October 2, 2025
Version: v0.0.2

This guide helps you resolve common issues when building, testing, or using FerrisScript.

Quick Links:
Windows Issues | macOS Issues | Linux Issues | Build Errors | Godot Integration | Runtime Errors

Platform-Specific Issues
Common Build Errors
Godot Integration
Runtime Errors
Getting More Help

Platform-Specific Issues

Windows Issues

Issue: "error: linker `link.exe` not found"

Cause: Missing MSVC (Microsoft Visual C++) build tools required by Rust.

Solution:

Option A: Install Visual Studio 2019 or later (Recommended)
- Download: https://visualstudio.microsoft.com/downloads/
- Choose "Community Edition" (free)
- During installation, select:
  - ✅ "Desktop development with C++"
  - ✅ "MSVC v142 or later" build tools
  - ✅ "Windows 10 SDK" or later
- Restart your computer after installation
Option B: Install Build Tools for Visual Studio (Lighter)
- Download: https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022
- Run the installer
- Select "C++ build tools"
- Install

Verify installation:

# Check if MSVC is available
where link.exe

# Should output something like:
# C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\...\bin\Hostx64\x64\link.exe

Rebuild FerrisScript:
```
cargo clean
cargo build
```

Alternative: Use GNU toolchain (not recommended for Godot compatibility)

Issue: "error: could not find `windows_x86_64_msvc` crate"

Cause: Corrupted Rust toolchain or missing Windows target.

Solution:

Update Rust toolchain:
```
rustup update
```
Add Windows MSVC target (usually installed by default):
```
rustup target add x86_64-pc-windows-msvc
```
Clean and rebuild:
```
cargo clean
cargo build
```

Issue: Build freezes or takes extremely long

Cause: Low memory, antivirus interference, or disk space issues.

Solution:

Close unnecessary applications - Cargo build is memory-intensive
Check disk space:
- Need ~2GB free for Rust compilation
- target/ directory grows large during build
Temporarily disable antivirus - Windows Defender may scan every compiled file
- Settings → Virus & threat protection → Exclusions
- Add: Y:\cpark\Projects\RustyScript\target

Use fewer parallel jobs:

cargo build -j 2  # Limit to 2 parallel jobs

Check RAM usage (Task Manager → Performance)
- Minimum 4GB RAM recommended
- 8GB+ for faster builds

Issue: "error: command in project.json failed to run"

Cause: PowerShell execution policy or path issues.

Solution:

Check execution policy:
```
Get-ExecutionPolicy
```

If "Restricted", allow scripts:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Verify Rust is in PATH:
```
echo $env:PATH | Select-String cargo
```
If not found, add manually:
- Press Win + R, type sysdm.cpl
- Advanced → Environment Variables
- Add: C:\Users\YOUR_USERNAME\.cargo\bin

macOS Issues

Issue: "xcrun: error: invalid active developer path"

Cause: Missing Xcode Command Line Tools (required for compiling Rust on macOS).

Solution:

Install Xcode Command Line Tools:
```
xcode-select --install
```
Accept license agreement:
```
sudo xcodebuild -license accept
```

Verify installation:

xcode-select -p
# Should output: /Library/Developer/CommandLineTools

Rebuild FerrisScript:
```
cargo clean
cargo build
```

Alternative: Install full Xcode from App Store (larger download, includes more tools).

Issue: "ld: library not found for -lSystem"

Cause: Incomplete or corrupted Xcode installation.

Solution:

Reinstall Command Line Tools:

sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install

Reset Xcode developer directory:
```
sudo xcode-select --reset
```
Clean and rebuild:
```
cargo clean
cargo build
```

Issue: "error: linking with `cc` failed"

Cause: Incompatible SDK version or missing libraries.

Solution:

Check macOS SDK:
```
xcrun --show-sdk-path
```
Update Homebrew (if using):
```
brew update
brew upgrade
```
Install required libraries:
```
brew install llvm
```
Update Rust:
```
rustup update
```

Issue: Case-sensitive filesystem issues

Cause: macOS uses case-insensitive filesystem by default, but git preserves case.

Error Example:

cd ferrisscript  # ERROR: No such file or directory

Solution:

Use the correct capitalization:

cd FerrisScript  # Correct

Note: This was a bug in earlier README versions (fixed in v0.0.2).

Linux Issues

Issue: "error: linking with `cc` failed" or "cannot find -lclang"

Cause: Missing build essentials or libclang (required for gdext bindings).

Solution (Ubuntu/Debian):

sudo apt update
sudo apt install build-essential libclang-dev pkg-config

Solution (Fedora/RHEL):

sudo dnf install gcc clang-devel pkg-config

Solution (Arch Linux):

sudo pacman -S base-devel clang

Verify installation:

clang --version
pkg-config --version

Issue: "error: could not compile `gdext`"

Cause: Incompatible or missing libclang version.

Solution:

Install specific libclang version:

# Ubuntu/Debian
sudo apt install libclang-14-dev

# Fedora
sudo dnf install clang-devel

Set LIBCLANG_PATH environment variable:

export LIBCLANG_PATH=/usr/lib/llvm-14/lib
cargo build

Make permanent (add to ~/.bashrc or ~/.zshrc):

echo 'export LIBCLANG_PATH=/usr/lib/llvm-14/lib' >> ~/.bashrc
source ~/.bashrc

Issue: "directory not found: ferrisscript"

Cause: Case-sensitive filesystem + incorrect directory name.

Error:

cd ferrisscript  # ERROR (lowercase)

Solution:

Use the correct capitalization:

cd FerrisScript  # Correct (capital F and S)

Why? Linux filesystems are case-sensitive, unlike Windows. The repository name is FerrisScript.

Issue: Permission denied errors

Cause: Insufficient permissions or incorrect ownership.

Solution:

For build directory issues:

# Take ownership of target directory
sudo chown -R $USER:$USER target/

For cargo cache issues:

# Reset cargo permissions
sudo chown -R $USER:$USER ~/.cargo/

Never use sudo with cargo:

# DON'T do this:
sudo cargo build  # ❌ Bad - creates permission issues

# Instead:
cargo build  # ✅ Good

Common Build Errors

Error: "rustc version mismatch"

Cause: Rust version too old or rustup out of date.

Solution:

# Update Rust to latest stable
rustup update stable

# Verify version (need 1.70+)
rustc --version

# Should output: rustc 1.70.0 or higher

Error: "failed to resolve: use of undeclared crate"

Cause: Missing dependencies or corrupted Cargo.lock.

Solution:

# Clean build artifacts
cargo clean

# Update dependencies
cargo update

# Rebuild
cargo build --workspace

If still failing:

Delete Cargo.lock and target directory:

rm Cargo.lock
rm -rf target/
cargo build

Check internet connection (cargo needs to download crates)

Error: "multiple definition of `__getreent`" (Windows)

Cause: Conflict between MinGW and MSVC toolchains.

Solution:

Use MSVC toolchain consistently:

# Set default toolchain
rustup default stable-x86_64-pc-windows-msvc

# Remove MinGW if present
rustup toolchain uninstall stable-x86_64-pc-windows-gnu

# Rebuild
cargo clean
cargo build

Error: "error: cannot find macro `gdextension_api` in this scope"

Cause: godot_bind crate has dependency issues with gdext.

Solution:

Clean rebuild:

cargo clean
cargo build --package ferrisscript_godot_bind

Update gdext dependency (if on main branch):
```
cargo update -p gdext
```
If still failing, check gdext compatibility:
- FerrisScript v0.0.1 uses gdext v0.1.x
- Godot 4.2+ required

Error: Build succeeds but tests fail

Symptoms:

cargo test  # Some tests fail

Solution:

Check if specific crate has issues:

cargo test --package rustyscript_compiler  # Test compiler only
cargo test --package rustyscript_runtime    # Test runtime only

Run with backtrace for details:
```
RUST_BACKTRACE=1 cargo test
```

Check test output:

cargo test -- --nocapture  # Show println! output

Report bug if tests fail on clean install:
- Open an issue
- Include test output and rustc --version

Godot Integration

Note: Godot integration testing is partially deferred in v0.0.1. Full automation planned for v0.0.3+. See FUTURE_AUTOMATION.md.

Issue: Godot doesn't recognize `.gdextension` file

Symptoms:

.ferris scripts don't appear in Godot
No "FerrisScript" option in script creation dialog
Errors in Godot console about missing extension

Solution:

Verify .gdextension file location:

godot_test/addons/ferrisscript/ferrisscript.gdextension

Check .gdextension syntax:

[configuration]
entry_symbol = "gdext_rust_init"

[libraries]
linux.x86_64 = "res://addons/ferrisscript/bin/libferrisscript_godot_bind.so"
macos.x86_64 = "res://addons/ferrisscript/bin/libferrisscript_godot_bind.dylib"
windows.x86_64 = "res://addons/ferrisscript/bin/ferrisscript_godot_bind.dll"

Verify library file exists:

# Linux
ls godot_test/addons/ferrisscript/bin/*.so

# macOS
ls godot_test/addons/ferrisscript/bin/*.dylib

# Windows
dir godot_test\addons\ferrisscript\bin\*.dll

Restart Godot editor - GDExtensions load at startup
Check Godot version - Must be 4.2 or later
```
Godot → Help → About
```

Issue: "Entry point not found" error in Godot

Cause: Library built for wrong platform or architecture.

Solution:

Verify your platform:

rustc --version --verbose
# Look for "host:" line

Build for correct target:

# Linux
cargo build --package ferrisscript_godot_bind --target x86_64-unknown-linux-gnu

# macOS
cargo build --package ferrisscript_godot_bind --target x86_64-apple-darwin

# Windows
cargo build --package ferrisscript_godot_bind --target x86_64-pc-windows-msvc

Rebuild and replace library:

cargo build --package ferrisscript_godot_bind --release
# Copy from target/release/ to godot_test/addons/ferrisscript/bin/

Issue: `.ferris` scripts cause Godot to crash

Symptoms:

Godot crashes when loading scene with FerrisScript
"Segmentation fault" or similar errors

Possible Causes:

Runtime panic in FerrisScript code
Invalid Godot API usage
Memory corruption (rare in v0.0.1)

Solution:

Enable debug logging:
- Add println! statements in your .ferris file
- Check Godot Output console

Test script in isolation:

cargo run --bin rustyscript_runtime your_script.ferris

Simplify script to minimal reproduction:

fn main() {
    println!("Hello");  // Start simple
}

Check Godot console for error messages
Report bug if crash persists:
- Open issue
- Include crash log, .ferris script, Godot version

Issue: Inspector properties don't update when switching from script with type errors

Symptoms:

Attach a .ferris script with a type error (e.g., @export let mut health: i32 = "Banana";)
Godot console shows compilation error (E200: Type mismatch)
Switch to a different valid .ferris script
Inspector shows "Script path changed" message
But Inspector properties don't update - still shows old/empty properties

Example Error:

ERROR: crates\godot_bind\src\lib.rs:719 - Failed to compile script 'res://scripts/inspector_minimal.ferris': Error[E200]: Type mismatch
ERROR: Type mismatch in global variable 'health': expected i32, found String at line 1, column 1
ERROR: 
ERROR:  1 | @export let mut health: i32 = "Banana";
ERROR:    | ^ Value type String cannot be coerced to i32

Then switching scripts:

Set script_path
📝 Script path changed: res://scripts/inspector_minimal.ferris → res://scripts/other_script.ferris

Cause: When a script fails to compile, the property list isn't cleared. Switching to a new script doesn't trigger property list refresh if the old script left the node in an error state.

Solution (Workaround):

Fix type errors before switching scripts

// ✅ Correct
@export let mut health: i32 = 100;

Or manually refresh Inspector:
- Click on a different node
- Click back on the FerrisScriptNode
- Inspector should now show correct properties
Or reload the scene:
- Close and reopen the scene
- Properties will refresh correctly

Status: Known issue in v0.0.4. Will be fixed in v0.0.5 by:

Clearing property list on compilation failure
Calling notify_property_list_changed() even on error paths
Improving error state handling in load_script()

Workaround Impact: Low - only affects development workflow when fixing type errors.

Runtime Errors

Error: "type mismatch" when running `.ferris` script

Example:

Error: Expected type i32, found f32

Cause: Type checker caught an error (working as intended).

Solution:

Fix type in your .ferris file:

// ❌ Wrong
let x: i32 = 3.14;  // Error: f32 assigned to i32

// ✅ Correct
let x: f32 = 3.14;  // Explicit f32
// or
let x = 3;  // Integer literal (i32 by default)

Error: "unknown identifier" at runtime

Cause: Variable not declared or scope issue.

Solution:

Check variable declaration:

// ❌ Wrong - variable used before declaration
fn main() {
    println!(x);  // Error: unknown identifier 'x'
    let x = 5;
}

// ✅ Correct
fn main() {
    let x = 5;
    println!(x);
}

Error: Script runs but produces wrong output

Debugging steps:

Add println! statements:

fn calculate(x: i32) -> i32 {
    println!("Input: {}", x);  // Debug
    let result = x * 2;
    println!("Result: {}", result);  // Debug
    result
}

Run tests:
```
cargo test
```
Check type coercion:
- i32 → f32 works (automatic)
- f32 → i32 requires explicit cast (not supported in v0.0.1)

Verify operator precedence:

let x = 2 + 3 * 4;  // Result: 14 (not 20)

Getting More Help

Before Asking for Help

✅ Check FAQ.md
✅ Check this troubleshooting guide
✅ Search existing issues
✅ Try clean rebuild: cargo clean && cargo build
✅ Update Rust: rustup update

Where to Get Help

Bug Reports: Open an issue
Questions: GitHub Discussions Q&A
Feature Requests: Discussions - Ideas
Documentation Issues: Doc template

Information to Include in Bug Reports

When reporting issues, include:

Environment:
- OS and version (Windows 11, Ubuntu 22.04, macOS 13, etc.)
- Rust version (rustc --version)
- FerrisScript version or commit hash
- Godot version (if applicable)
Error message: Copy full error output
Steps to reproduce: Minimal example that triggers the issue
Expected vs actual behavior
Relevant code: .ferris file or build command

Made with 🦀 and ❤️ for the Godot community

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FerrisScript Troubleshooting Guide

Table of Contents

Platform-Specific Issues

Windows Issues

Issue: "error: linker `link.exe` not found"

Issue: "error: could not find `windows_x86_64_msvc` crate"

Issue: Build freezes or takes extremely long

Issue: "error: command in project.json failed to run"

macOS Issues

Issue: "xcrun: error: invalid active developer path"

Issue: "ld: library not found for -lSystem"

Issue: "error: linking with `cc` failed"

Issue: Case-sensitive filesystem issues

Linux Issues

Issue: "error: linking with `cc` failed" or "cannot find -lclang"

Issue: "error: could not compile `gdext`"

Issue: "directory not found: ferrisscript"

Issue: Permission denied errors

Common Build Errors

Error: "rustc version mismatch"

Error: "failed to resolve: use of undeclared crate"

Error: "multiple definition of `__getreent`" (Windows)

Error: "error: cannot find macro `gdextension_api` in this scope"

Error: Build succeeds but tests fail

Godot Integration

Issue: Godot doesn't recognize `.gdextension` file

Issue: "Entry point not found" error in Godot

Issue: `.ferris` scripts cause Godot to crash

Issue: Inspector properties don't update when switching from script with type errors

Runtime Errors

Error: "type mismatch" when running `.ferris` script

Error: "unknown identifier" at runtime

Error: Script runs but produces wrong output

Getting More Help

Before Asking for Help

Where to Get Help

Information to Include in Bug Reports

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History

TROUBLESHOOTING.md

File metadata and controls

FerrisScript Troubleshooting Guide

Table of Contents

Platform-Specific Issues

Windows Issues

Issue: "error: linker link.exe not found"

Issue: "error: could not find windows_x86_64_msvc crate"

Issue: Build freezes or takes extremely long

Issue: "error: command in project.json failed to run"

macOS Issues

Issue: "xcrun: error: invalid active developer path"

Issue: "ld: library not found for -lSystem"

Issue: "error: linking with cc failed"

Issue: Case-sensitive filesystem issues

Linux Issues

Issue: "error: linking with cc failed" or "cannot find -lclang"

Issue: "error: could not compile gdext"

Issue: "directory not found: ferrisscript"

Issue: Permission denied errors

Common Build Errors

Error: "rustc version mismatch"

Error: "failed to resolve: use of undeclared crate"

Error: "multiple definition of __getreent" (Windows)

Error: "error: cannot find macro gdextension_api in this scope"

Error: Build succeeds but tests fail

Godot Integration

Issue: Godot doesn't recognize .gdextension file

Issue: "Entry point not found" error in Godot

Issue: .ferris scripts cause Godot to crash

Issue: Inspector properties don't update when switching from script with type errors

Runtime Errors

Error: "type mismatch" when running .ferris script

Error: "unknown identifier" at runtime

Error: Script runs but produces wrong output

Getting More Help

Before Asking for Help

Where to Get Help

Information to Include in Bug Reports

Issue: "error: linker `link.exe` not found"

Issue: "error: could not find `windows_x86_64_msvc` crate"

Issue: "error: linking with `cc` failed"

Issue: "error: linking with `cc` failed" or "cannot find -lclang"

Issue: "error: could not compile `gdext`"

Error: "multiple definition of `__getreent`" (Windows)

Error: "error: cannot find macro `gdextension_api` in this scope"

Issue: Godot doesn't recognize `.gdextension` file

Issue: `.ferris` scripts cause Godot to crash

Error: "type mismatch" when running `.ferris` script