Troubleshooting Guide

July 23, 2026 · View on GitHub

Debugging Tools

LLxprt Code has built-in debugging tools. Start here before digging into logs.

LLXPRT_DEBUG Environment Variable

Enable debug logging with namespace filtering:

# All debug output
LLXPRT_DEBUG='*' llxprt

# Specific namespaces
LLXPRT_DEBUG='llxprt:shell' llxprt
LLXPRT_DEBUG='llxprt:core:*' llxprt
LLXPRT_DEBUG='llxprt:tools:*,llxprt:shell' llxprt

Available namespaces:

Namespace	What it logs
`llxprt:shell`	Shell command execution
`llxprt:scheduler`	Tool scheduling and dispatch
`llxprt:core:hooks:*`	Hook system (planner, registry, runner)
`llxprt:core:hook-triggers:*`	Model and tool hook triggers
`llxprt:core:tools:mcp-client`	MCP server communication
`llxprt:tools:modifiable-tool`	Tool modification/interception
`*`	Everything

You can also use DEBUG=llxprt:* (the legacy form still works if the value contains llxprt namespaces), but LLXPRT_DEBUG is preferred and doesn't conflict with other tools.

Additional environment variables:

Variable	Description
`DEBUG_LEVEL`	Log level (e.g., `debug`, `info`, `warn`)
`DEBUG_OUTPUT`	Output target (e.g., file path)
`DEBUG_ENABLED`	`true`/`false` to force on/off

/dumpcontext

Dumps the full model context (system prompt, conversation history, tool definitions, context files) to a JSON file so you can inspect exactly what's being sent to the provider:

/dumpcontext          # Show status and dump directory
/dumpcontext now      # Dump on next request only
/dumpcontext on       # Dump before every request
/dumpcontext error    # Dump only when errors occur
/dumpcontext off      # Stop dumping

Dumps are saved to <cache>/dumps/ (see Application Directories) as timestamped JSON files.

/debug

Control the debug logger at runtime — same namespaces as LLXPRT_DEBUG but toggled without restarting. In interactive mode, press F12 to open the debug console.

/debug status                    # Show current debug state
/debug enable                    # Enable all llxprt:* namespaces
/debug enable llxprt:shell       # Enable a specific namespace
/debug disable                   # Disable debug logging
/debug level debug               # Set log level
/debug output /tmp/llxprt.log    # Send debug output to a file
/debug persist                   # Toggle saving debug config across sessions

/logging

Manages conversation logging (recording request/response pairs for later review), not debug logging:

/logging status                     # Show if conversation logging is on
/logging enable                     # Enable conversation logging
/logging disable                    # Disable conversation logging
/logging show [N]                   # Show last N log entries (default 50)
/logging redaction                  # View redaction settings
/logging redaction --api-keys=true  # Configure what gets redacted

/diagnostics

Run system diagnostics to check your environment:

/diagnostics

Reports on Node.js version, installed providers, keyring availability, sandbox readiness, and other environment checks.

LLxprt Code stores named keys in the OS keyring (macOS Keychain, GNOME Keyring, Windows Credential Manager) via @napi-rs/keyring. If the keyring is unavailable, it falls back to encrypted file storage in the OS-standard data directory (via env-paths):

macOS: ~/Library/Application Support/llxprt-code/secure-store/
Linux: ~/.local/share/llxprt-code/secure-store/
Windows: %LOCALAPPDATA%\llxprt-code\Data\secure-store (see Application Directories)

To check which backend is active:

LLXPRT_DEBUG='*' llxprt 2>&1 | grep -i keyring

Look for @napi-rs/keyring not loaded — unavailable in the output — that means it's using the encrypted file fallback.

Named keys (recommended):

Save a key from inside a session:

/key save xai-prod your-api-key-value

Then use it at startup:

llxprt --provider xai --key-name xai-prod

Common keyring issues:

Linux headless/SSH: No D-Bus session → keyring unavailable → falls back to encrypted files. This is fine — the fallback is secure.
Linux containers: Same situation. Use --keyfile or --key if the encrypted fallback doesn't work.
macOS: Keychain should work out of the box. If not, check security list-keychains in Terminal.

Common Authentication Errors

Failed to login. Message: Request contains an invalid argument

Google Workspace or Google Cloud accounts may not qualify for the free Gemini API tier. Workarounds:

Set GOOGLE_CLOUD_PROJECT to your project ID
Get an API key from AI Studio

API key not found / Invalid API key

Your key is missing or revoked. Check:

The key is set: llxprt --provider xai --key-name xai-prod (does it prompt?)
The key works: test it with curl against the provider API
The provider dashboard shows the key as active

UNABLE_TO_GET_ISSUER_CERT_LOCALLY

You may be on a corporate network with a firewall that intercepts and inspects SSL/TLS traffic. This often requires a custom root CA certificate to be trusted by Node.js.

First try setting NODE_USE_SYSTEM_CA; if that does not resolve the issue, set NODE_EXTRA_CA_CERTS:

# Try this first - use OS native certificate store
export NODE_USE_SYSTEM_CA=1

# If that doesn't work, point to your corporate CA cert
export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt

OAuth Troubleshooting

OAuth tokens are stored in the OS keyring (same as named keys). If authentication fails:

Try logging out and re-authenticating: /auth anthropic logout then /auth anthropic enable
If on a headless machine, use --nobrowser for manual code entry
Check LLXPRT_DEBUG='*' output for token refresh errors

See OAuth Setup for detailed OAuth configuration.

Streaming and Retry Issues

stream interrupted, retrying (attempt 2/6)

LLxprt detected a transient network issue and is retrying automatically with exponential backoff. Usually no action needed. If persistent:

Check your network connection
Look for local proxy/firewall interference
Increase retry settings: /set retrywait 5000

Request would exceed the <limit> token context window even after compression

The conversation plus system prompt exceeds the model's context limit. Solutions:

Run /compress to compress history
Shorten your LLXPRT.md files
Lower max output tokens: /set modelparam max_tokens 4096
Start fresh: /clear

PowerShell @ Symbol Issues

PowerShell's IntelliSense treats @ as a hashtable literal start, causing lag. LLxprt automatically detects PowerShell and enables + as an alternative prefix:

# Use + instead of @ in PowerShell
+path/to/file.txt

Common Error Messages

EADDRINUSE (MCP server)

Another process is using that port. Stop it or configure a different port in your MCP server settings.

Command not found

LLxprt isn't in your PATH. If installed globally: check npm root -g. If from source: use bun scripts/start.ts (the dev launcher) or run bun install then bun run start.

MODULE_NOT_FOUND

Run bun install to restore dependencies. If the error references a dist/ file, run bun run build (or npm run build) to recompile the TypeScript sources.

Operation not permitted

Sandbox is blocking the operation. See Sandboxing for how to adjust sandbox profiles.

CLI not interactive in CI environments

The is-in-ci package detects CI, CONTINUOUS_INTEGRATION, or any CI_* env var and forces non-interactive mode. Workaround: env -u CI_TOKEN llxprt

Exit Codes

Exit Code	Error Type	Description
41	`FatalAuthenticationError`	Authentication failed
42	`FatalInputError`	Invalid input (non-interactive mode)
43	Launcher runtime failure	Bundled Bun runtime missing, corrupt, wrong platform, or an unrecognized native format — reinstall `@vybestack/llxprt-code` or visit https://bun.sh
44	`FatalSandboxError`	Sandbox setup failed
52	`FatalConfigError`	Invalid settings.json
53	`FatalTurnLimitedError`	Max turns reached (non-interactive mode)

Sandbox Issues

See Sandboxing for full sandbox documentation including Docker/Podman setup, credential proxying, SSH agent passthrough, and sandbox profiles.

Quick troubleshooting:

Docker daemon not running: Start Docker Desktop (macOS) or sudo systemctl start docker (Linux).

Podman machine not running (macOS): podman machine start. If stuck: podman machine stop && podman machine rm && podman machine init && podman machine start.

Credential proxy not starting: The proxy needs a working OS keyring. On headless Linux, use --key or --keyfile instead.

SSH agent issues in Podman macOS: Launchd-managed sockets don't work in the VM. Create a dedicated socket:

ssh-agent -a ~/.llxprt/ssh-agent.sock
export SSH_AUTH_SOCK=~/.llxprt/ssh-agent.sock
ssh-add ~/.ssh/id_ed25519
llxprt --sandbox-engine podman

Podman macOS: exit code 137 / OOM with high memory settings: The Podman VM memory is lower than the container --memory limit. On macOS, Podman containers run inside a VM, and the VM memory is the hard ceiling — LLxprt container flags do not resize the VM. Check with podman machine inspect --format '{{.Resources.Memory}}' and resize with podman machine set --memory <MB>. See Sandbox troubleshooting for full details.

Enable sandbox debug output:

LLXPRT_DEBUG='*' llxprt --sandbox "your prompt"

FAQs

How do I update LLxprt Code?

npm (global install): npm install -g @vybestack/llxprt-code@latest
Homebrew: brew upgrade llxprt-code
From source: Pull the latest source, run bun install, then bun run start (or bun scripts/start.ts for the dev launcher).

Where are config files stored?

User settings live in LLxprt's config directory (e.g. ~/.config/llxprt-code/settings.json on Linux); project settings live at .llxprt/settings.json in your project root. See Configuration.

Why don't I see cached token counts in /stats?

Cache metrics only appear when the provider supports and reports them. OAuth users may not see cache stats if the backend doesn't support cached content creation.

Building from Source

The CLI's installed command uses platform-native launchers (packages/cli/bin/llxprt) that resolve the package-bundled Bun and execute the TypeScript entrypoint (packages/cli/index.ts) directly — no Node process is started on the installed path. No pre-compiled CLI dist/ artifact or retired bundle/llxprt.js artifact is required for the CLI to run.

To build from source:

git clone https://github.com/vybestack/llxprt-code.git
cd llxprt-code
bun install
bun run start

For development, use the dev launcher:

bun scripts/start.ts

Type checking uses tsc --noEmit (no JavaScript output is produced):

bun run typecheck

Platform Caveats

Windows pty Behavior

On Windows, the node-pty module has a known terminal resize race condition (Cannot resize a pty that has already exited). The CLI silences this specific error at the process level and uses @lydell/node-pty (with node-pty as fallback) — not the Bun adapter. The bun-pty adapter (packages/core/src/utils/bunPtyAdapter.ts) is POSIX-only and is not used on Windows. If you encounter terminal sizing or resize issues on Windows, use a compatible terminal emulator; the resize race is in node-pty itself, not the Bun runtime.

The @lydell/node-pty ConPTY path is verified under Bun on Windows by the nightly native-module smoke. A hosted Windows Server 2025 run passed with Bun 1.3.14, including streamed PTY data and a real zero exit callback, so Bun on Windows continues to use this path. See the hosted smoke result.