Skip to content

Troubleshooting

This page collects common setup and first-run fixes for the installed toolchain path. Contributor-only source-build notes are called out separately.

incan: command not found after toolchain install

The toolchain installer links incan and incan-lsp into INCAN_BIN_DIR, defaulting to ~/.local/bin. Make sure that directory is on your PATH:

export PATH="$HOME/.local/bin:$PATH"
command -v incan
incan --version

If you installed with a custom bin directory, use that path instead:

curl -fsSL https://github.com/encero-systems/incan/releases/latest/download/install.sh | INCAN_BIN_DIR="$HOME/bin" bash
export PATH="$HOME/bin:$PATH"

Shell or editor is using an old incan / incan-lsp

This usually means your shell and editor resolve different binaries. Check both commands:

command -v incan
command -v incan-lsp
incan --version
incan tools doctor

For VS Code/Cursor, also check the Incan settings:

{
  "incan.lsp.path": "",
  "incan.compiler.path": ""
}

Leaving these empty makes the extension use workspace binary discovery or PATH. If you set incan.lsp.path, use a literal executable path such as /Users/me/.local/bin/incan-lsp; the setting does not expand $HOME, ~, or shell commands. The extension warns when either path setting contains shell syntax, points at a missing file, or points at a non-executable file.

After changing paths or reinstalling, reload the editor window so it starts a new language-server process:

  1. Run Incan: Doctor from the command palette and check the Incan output channel.
  2. Run Developer: Reload Window from the command palette.
  3. Reopen a .incn file.
  4. Re-run Incan: Doctor if diagnostics still look stale.

Contributor source builds

If you are working from a compiler checkout, use repository make targets instead of the toolchain installer:

cd /path/to/incan
make build

On local machines, make build builds the compiler and LSP with cargo build --features lsp, then links ~/.cargo/bin/incan to target/debug/incan and ~/.cargo/bin/incan-lsp to target/debug/incan-lsp. Keep ~/.cargo/bin early enough in your PATH that both tools resolve there.

If you intentionally want the release binary from a checkout:

make release
./target/release/incan --version

Rust backend provisioning fails

The direct installer and pipx adapter provision stable Rust through rustup when rustup, cargo, or rustc are missing, then run rustup target add wasm32-wasip1. The npm adapter does not run lifecycle scripts or bootstrap Rust during package installation. If installer-backed provisioning fails on a fresh machine, check whether your network can reach the rustup bootstrap script and Rust distribution servers:

command -v rustup || true
command -v cargo || true
command -v rustc || true
rustup target list --installed 2>/dev/null || true

Use INCAN_SKIP_RUST_INSTALL=1 or install.sh --skip-rust only when your environment manages Rust separately. In that mode, make sure cargo, rustc, and wasm32-wasip1 are already available before running incan run, incan test, incan build, or package checks that load vocab companions.

Builds are slow the first time

The first incan build, incan test, or generated project run needs either a compatible full-stdlib Loaf supplied by an Oven-enabled toolchain or a receipt-bound project extension prepared from that base. A miss explains whether to install or reinstall the toolchain or run incan oven bake --project for declared project Rust dependencies. The normal command never runs the internal compatibility publisher or compiles a closure through Cargo automatically.

Preparing a compatibility closure needs its publisher inputs

The internal compatibility publisher may need Rust ecosystem inputs that are already available to it. This is not a normal incan build, incan run, or incan test concern.

For restricted or offline environments, run the supported preflight before the build:

incan tools doctor

The doctor report includes advisory diagnostics for the publisher's local dependency inputs. Normal Oven commands do not accept Cargo offline, lock-enforcement, or feature flags: they select a previously prepared receipt-compatible closure. If an explicit publisher preparation needs networked Cargo inputs, prepare that closure under the publisher's own documented policy before normal developer commands run.

macOS: toolchain/linker issues

If you see errors about a missing C toolchain or linker, install Xcode Command Line Tools:

xcode-select --install

Still stuck?

If you’re still stuck, please open an issue and include your OS, architecture, exact commands, and full error output.