Troubleshooting¶

This guide covers the most common SuperQode setup and runtime issues.

Start With Doctor Commands¶

Run the checks that match the feature you are using:

superqode doctor
superqode providers doctor
superqode runtime list
superqode harness doctor --spec harness.yaml
superqode sandbox doctor
superqode memory doctor
superqode trust doctor

Use JSON output when you need to paste diagnostics into an issue:

superqode doctor --json
superqode providers doctor openai --json
superqode harness doctor --spec harness.yaml --json

Installation Issues¶

`ModuleNotFoundError: No module named 'superqode'`¶

Reinstall SuperQode in the environment you are using:

python -m pip install --upgrade superqode
python -c "import superqode; print(superqode.__version__)"

With uv:

uv tool install --force superqode
superqode --version

For source installs:

git clone https://github.com/SuperagenticAI/superqode.git
cd superqode
python -m pip install -e .

The `superqode` command is not found¶

Check that the Python scripts directory is on PATH:

python -m site --user-base
python -m pip show superqode

If you installed with uv, check:

uv tool list

TUI Connection Problems¶

The TUI starts but no model is connected¶

Open the connection picker:

:connect

Or connect directly:

:connect byok openai gpt-4o-mini
:connect local ollama qwen3:8b
:connect acp opencode

Then confirm state:

:status

Provider authentication fails¶

Check the provider-specific environment variable:

echo "$OPENAI_API_KEY"
echo "$ANTHROPIC_API_KEY"
echo "$GOOGLE_API_KEY"
superqode auth check openai
superqode providers doctor openai

Never place API keys directly in documentation, issues, logs, or committed config. In superqode.yaml, reference environment variables:

providers:
  openai:
    api_key_env: OPENAI_API_KEY

ACP agent is unavailable¶

List and inspect agents:

superqode agents list
superqode agents doctor opencode
superqode agents doctor opencode --live

For OpenCode:

npm i -g opencode-ai
opencode --help
superqode connect acp opencode

Harness Problems¶

Harness YAML does not validate¶

Run:

superqode harness validate --spec harness.yaml
superqode harness inspect --spec harness.yaml

Common fixes:

use flavor: coding or flavor: no_tool
use a known runtime backend such as builtin, openai-agents, adk, deepagents, pydanticai, or codex-sdk
keep execution_policy.allow_write and execution_policy.allow_shell false for no-tool harnesses
define agents as a YAML list

Optional runtime backend is missing¶

List backends:

superqode harness list-backends
superqode runtime doctor pydanticai

Install only the backend you need:

python -m pip install "superqode[pydanticai]"
python -m pip install "superqode[deepagents]"
python -m pip install "superqode[openai-agents]"
python -m pip install "superqode[adk]"
python -m pip install "superqode[codex-sdk]"

A run did something unexpected¶

Inspect persisted events:

superqode harness runs
superqode harness events <run-id>
superqode harness graph <run-id>
superqode harness graph <run-id> --json

Run doctor with the same runtime and sandbox overrides:

superqode harness doctor --spec harness.yaml --runtime pydanticai --sandbox local

Sandbox And Permission Problems¶

Shell commands are blocked¶

Check the active sandbox and harness policy:

superqode sandbox doctor
superqode harness inspect --spec harness.yaml

In the TUI:

:sandbox
:sandbox workspace-write
:status

If shell should be allowed, the harness must allow it:

execution_policy:
  sandbox: local
  approval_profile: balanced
  allow_shell: true
  allowed_commands:
    - uv run pytest

A tool call is waiting for approval¶

In the TUI:

:approve
:approve 1 always
:reject
:reject 1 "use a safer command"

Use always only when you intentionally trust similar calls for the current session.

MCP Problems¶

MCP server is not available¶

Check config and dependencies:

superqode config init
node --version
npx --version

Example mcp_servers config:

mcp_servers:
  filesystem:
    transport: stdio
    enabled: true
    auto_connect: true
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - "."

Use mcpServers only when importing external MCP config. New SuperQode config should use mcp_servers.

Local Model Problems¶

Ollama model does not appear¶

Check Ollama:

ollama list
ollama serve
ollama pull qwen3:8b
superqode providers doctor ollama --live

Connect:

:connect local ollama qwen3:8b

DS4 is slow on first request¶

DS4 may warm up the model on connect. To skip warm-up:

export SUPERQODE_DS4_WARMUP=0

Then point SuperQode at the DS4 endpoint if needed:

export DS4_HOST=http://127.0.0.1:8000/v1
superqode providers guide ds4

Session And Export Problems¶

You cannot find an old session¶

superqode sessions list
superqode sessions tree
superqode sessions show <session-id>

You need to hand off a session¶

superqode share create <session-id>
superqode share list
superqode share import <artifact.superqode-share.json> --session-id imported

Export failed¶

Try a specific format and path:

superqode sessions export <session-id> --format markdown --output session.md
superqode sessions export <session-id> --format json --output session.json

Project Trust And Plugins¶

If plugins, hooks, or MCP config are blocked, inspect project trust:

superqode trust status
superqode trust doctor
superqode trust yes
superqode plugins doctor

Only trust projects whose local executable config you have reviewed.

Getting Help¶

When opening an issue, include:

SuperQode version from superqode --version
Python version from python --version
operating system
command you ran
relevant doctor --json output with secrets removed
minimal superqode.yaml or harness.yaml that reproduces the issue

Links: