Troubleshooting

Diagnostic Tools

Run heretic-cli doctor to diagnose common issues:

heretic-cli doctor
heretic-cli doctor --fix    # Auto-fix issues where possible

Use --verbose on any command for debug output:

heretic-cli run claude --verbose

Common Issues

Copilot Tokens Missing from Containers

Ensure the agent profile has provider: copilot. Copilot tokens are only injected for agents with this provider.

If the provider field is missing, it is inferred from agent_type (copilot-cli → copilot). Always set provider explicitly.

The .claude.json onboarding seed may be missing. Delete the session directory and re-run:

rm -rf .heretic/temp/default/
heretic-cli run claude

Empty Env Vars Overriding Container Defaults

The CLI filters empty env vars except for intentionally empty ones set in config.env (e.g., ANTHROPIC_AUTH_TOKEN: "" for OAuth mode). Use --verbose to see which env vars are being set.

Secret Script Fails on Windows

Ensure the script extension matches the expected shell:

.cmd for cmd.exe
.ps1 for PowerShell
.sh for Git Bash/WSL

Docker Not Available

Run heretic-cli doctor to check Docker availability. Ensure Docker Desktop is running (macOS/Windows) or the Docker daemon is active (Linux).

Profile Validation Errors

# Check all profiles
heretic-cli agents validate

# Check specific profile with details
heretic-cli agents validate claude --verbose

# Check local overrides
heretic-cli local-validate

Kilocode Auth Fails

Ensure the profile has provider: kilocode. Without it, the fallback inference returns anthropic and kilo-auth.json won't be created. Delete the session directory and re-run:

rm -rf .heretic/temp/default/
heretic-cli run kilocode

MCP Config Not Applied

Check whether an existing .mcp.json in your project root is taking precedence. Set mcp_override: true in your profile or local override to force the profile-defined MCP servers.

Sidecar Commands Not Working

If npm, python3, or other sidecar-routed commands fail:

# 1. Check BUILD_SIDECARS is set
docker exec <container> echo $BUILD_SIDECARS | jq .

# 2. List generated wrappers
docker exec <container> ls /opt/sidecar/wrappers/

# 3. Test sidecar-exec directly
docker exec <container> sidecar-exec node npm --version

# 4. Check sidecar health
docker exec <container> curl http://node-sidecar:8080/health

# 5. Verify docker.sock access (runner: docker with dind: true)
docker exec <container> docker ps

Common causes:

BUILD_SIDECARS is empty or malformed JSON — check with echo $BUILD_SIDECARS | jq .
Sidecar container not running — check with docker compose ps
Missing dind: true in profile when using runner: docker
Wrapper directory not in PATH — check with echo $PATH | tr ':' '\n' | grep sidecar

See Sidecars for full configuration details.

SSH Backend Not Working

If SSH-routed commands fail or time out:

# 1. Check SSH env vars are set
docker exec <container> env | grep SSH_

# 2. Test SSH connectivity
docker exec <container> ssh -o StrictHostKeyChecking=no \
    -p ${SSH_PORT:-22} -i ${SSH_KEY_PATH:-/home/agent/.ssh/id_rsa} \
    ${SSH_USER:-agent}@${SSH_HOST} echo "connected"

# 3. Check key permissions (must be 600)
docker exec <container> ls -la /home/agent/.ssh/id_rsa

# 4. Check host_cwd exists on remote
docker exec <container> ssh -o StrictHostKeyChecking=no \
    ${SSH_USER:-agent}@${SSH_HOST} "ls -la ${SSH_HOST_CWD}"

# 5. Verbose SSH debug
docker exec <container> ssh -vvv -o StrictHostKeyChecking=no \
    ${SSH_USER:-agent}@${SSH_HOST} echo "debug"