Wiki / Reference

Troubleshooting#

Start with portcode doctor: it tests providers, the Rust toolchain and the engines, and says what to fix.

Install and update#

GLIBC_2.39 not found on Linux. This only affected the first upload of v0.1.0. Current archives need glibc 2.34 or newer (Ubuntu 22.04, Debian 12). Run the installer again, or build with cargo install --git https://github.com/LakoMoor/portcode portcode-cli.

could not set up TLS or "builder error" on a minimal Linux. Install ca-certificates.

portcode: command not found after installing. The installer puts the binary in ~/.local/bin. Add that folder to your PATH, or set PORTCODE_INSTALL_DIR and install again.

Models and keys#

No API key. Type /key, or choose a local provider with /provider. Local servers need no key.

Connection refused. The local server is not running, or the port in portcode.json differs from the server's.

Model not found. /models shows the exact names the server offers.

Small context window. Set context_window for the model under "models" in portcode.json. PortCode then shortens tool output and compacts old turns to fit. See Providers and models.

The model writes tool calls as plain text, or breaks JSON. PortCode repairs the common cases. If a model still struggles, run portcode eval against it and try /style compact. For Qwen3.8 models see the profile notes in Providers and models.

In the app#

Nothing happens when I press esc. Cancelling needs two presses within two seconds. The footer shows press esc again to cancel after the first. ctrl+c cancels at once.

The agent stopped and shows "Needs your decision". It cannot continue without you. Answer the questions in the prompt and it carries on.

It keeps asking for permission. Answer a to always allow that exact request for the session, add allow rules in portcode.json (see Permissions), or use /yolo in a project you trust.

No suggestion appears in the prompt. It only shows in a fresh session with an empty prompt, and "suggest": false turns it off. If the provider has no key you get a local guess, not a model's.

/team says nothing happens. Switch to the team agent with tab after turning team mode on.

The venv tool says virtual environments are off. "venv": false is set, or you ran /venv off. Use /venv on.

python3 -m venv fails. Install Python 3 and, on Debian and Ubuntu, python3-venv.

Deep mode#

A deep tool says it needs deep mode. Start with --deep or type /deep.

An engine is missing. portcode engines list shows what is installed. portcode engines install core installs Capstone, Unicorn and LIEF. Engines that are not Python packages (Ghidra, rizin and others) are installed with your package manager; the list shows the command.

Subscriptions#

Claude Code or Codex is not found. Install the official CLI and sign in once, then check portcode doctor. See Claude Code and Codex.

Still stuck#

Open an issue at github.com/LakoMoor/portcode/issues with the output of portcode doctor and the version from portcode --version. Remove keys and personal paths first.

Windows#

Edit this page on GitHub