fun/web/documentation/troubleshooting/troubleshooting.md

---
layout: page
published: true
noToc: false
noComments: false
noDate: false
title: Troubleshooting Guide
subtitle: Common issues and quick fixes for build, includes, and REPL usage.
description: Common issues and quick fixes for build, includes, and REPL usage.
permalink: /documentation/troubleshooting/
lang: en
tags:
- build
- common
- fixes
- includes
- issues
- quick
- troubleshooting
---

This page lists common issues when building and running Fun from a source checkout and how to fix them quickly.

## Includes cannot be found

Error example:

<pre>Include error: cannot read '<io/console.fun>'</pre>

Fix:

- When running from the repository without installing, set `FUN_LIB_DIR` to the local `./lib` directory so angle‑bracket includes resolve correctly.

Linux/macOS/BSD:

<pre>export FUN_LIB_DIR="$(pwd)/lib"
./build/fun examples/include_lib.fun</pre>

Windows (PowerShell):

<pre>$env:FUN_LIB_DIR = "$PWD/lib"
./build/fun.exe .\examples\include_lib.fun</pre>

If `FUN_LIB_DIR` is not set, the interpreter tries a compile‑time `DEFAULT_LIB_DIR`, and finally falls back to `./lib` relative to the current working directory. Be mindful of where you run the `fun` binary from.

See includes.md for more details.

## REPL does not start

Symptoms:

- Running the executable just exits, or `--repl-on-error` is not recognized.

Fix:
- Build with `-DFUN_WITH_REPL=ON` and rebuild the `fun` target. Then launch without arguments:

<pre>cmake -S . -B build -DFUN_WITH_REPL=ON
cmake --build build --target fun
FUN_LIB_DIR="$(pwd)/lib" ./build/fun</pre>

See repl.md for usage tips and features.

## Linker errors for optional libraries (JSON, PCRE2, CURL, SQLite, etc.)

Symptoms:
- Build fails when enabling an optional feature.

Fix:
- Ensure the development packages for the chosen library are installed (headers + libs).
- Toggle features individually with `-DFUN_WITH_JSON=ON`, `-DFUN_WITH_PCRE2=ON`, etc., and verify your system provides them.

## Bytecode or opcode mismatch errors after refactors

Symptoms:
- Crashes or incorrect behavior after editing src/vm or src/bytecode.h.

Fix:
- Rebuild cleanly to ensure all amalgamated C units are recompiled.
- Verify opcode_names[] in src/vm.h matches enum ordering in src/bytecode.h.
- Re-run with `--trace` and (optionally) `--dump-bytecode` to inspect control flow.

## Paths differ when running from IDE vs. shell

Symptoms:
- Includes resolve in one environment but not the other; `./lib` fallback behaves differently.

Fix:
- Always set `FUN_LIB_DIR` explicitly in the run configuration of your IDE and in your shell session.
- Confirm the working directory of the launch configuration; relative includes use `$PWD`.

## Windows-specific quoting issues

Symptoms:
- Setting environment variables has no effect; include paths remain unresolved.

Fix:
- In CMD use: `set FUN_LIB_DIR=%CD%\lib && build\fun.exe examples\include_lib.fun`
- In PowerShell use: `$env:FUN_LIB_DIR = "$PWD\lib"; .\build\fun.exe .\examples\include_lib.fun`

## Getting help

- Run the interpreter with `--help` to see supported flags.
- Explore documentation/handbook.md and documentation/repl.md.
- Check the examples under `examples/` for an interactive tour.