Troubleshooting

Common failure modes and their fixes. If your issue isn't listed, file at https://github.com/armoriq/armorCopilot/issues with the Copilot log (find with ls -t ~/.copilot/logs/*.log | head -1).

Install issues

"missing required command: copilot"

The installer needs the GitHub Copilot CLI. Install it first:

curl -fsSL https://gh.io/copilot-install | bash

Then re-run the ArmorCopilot installer.

"Node.js >= 20 required"

The plugin's runtime needs Node 20+. Update via Homebrew (brew install node), nvm (nvm install 20), or your package manager.

"Failed to install plugin: Marketplace ... not found"

The marketplace registration didn't take. Common cause: the local clone path was used but .claude-plugin/marketplace.json is missing or malformed.

ls ~/.armoriq/armorCopilot/.claude-plugin/marketplace.json
cat ~/.armoriq/armorCopilot/.claude-plugin/marketplace.json | python3 -m json.tool

If the file is fine, re-run the installer with --uninstall first to clear any partial state.

Login redirect lands on platform.armoriq.ai instead of dev.armoriq.io

You have the wrong SDK version installed. The dev SDK should redirect to dev.armoriq.io. Run:

npm view @armoriq/sdk-dev version    # should be 0.3.4 or later
npm install -g @armoriq/sdk-dev@latest

Then re-run armoriq-dev login --product armorcopilot.

"Unknown product 'armorcopilot'"

The conmap-auto backend doesn't have the ProductSlug allowlist update. This was fixed in production around late May 2026. Confirm staging-api accepts it:

curl -s -X POST https://staging-api.armoriq.ai/auth/device/code \
  -H 'Content-Type: application/json' \
  -d '{"callback_url":"http://localhost:0","product":"armorcopilot"}'

Should return a JSON device-code response. If you get an "Unknown product" error, contact ArmorIQ support.

Runtime issues

Hooks aren't firing

First confirm the plugin is installed:

copilot plugin list

Then enable debug + check the log:

ARMORCOPILOT_DEBUG=true copilot --log-level debug -p "list files" --allow-all-tools
RECENT_LOG=$(ls -t ~/.copilot/logs/*.log | head -1)
grep -E "Loaded.*hook|\[armorcopilot\]" "$RECENT_LOG" | head -10

You should see:

[DEBUG] Loaded 8 hook(s) from 1 plugin(s)
[hook stderr] [armorcopilot] hook=SessionStart
[hook stderr] [armorcopilot] session started: <uuid>, mode=enforce

If you see "Loaded 0 hook(s)", the plugin's hooks/hooks.json isn't being discovered. Usually a malformed JSON or missing file.

"Cannot find module '/Users/.../scripts/bootstrap.mjs'"

Pre-Aug-2026 hooks.json used relative paths. Update by reinstalling:

copilot plugin uninstall armorcopilot
copilot plugin marketplace remove armorcopilot
curl -fsSL https://armoriq.ai/install_armorcopilot.sh | bash

The current hooks.json uses $CLAUDE_PLUGIN_ROOT for CWD-safe absolute paths.

"Invalid or expired API key"

Your ArmorIQ API key is from the wrong env. The SDK is staging-flavored (sdk-dev) but you logged in against prod (platform.armoriq.ai).

Fix: re-run device-code login pointing at dev:

armoriq-dev login --product armorcopilot

Verify the credential file:

grep apiKey ~/.armoriq/credentials.json

Then test against staging-api:

KEY=$(grep -oE 'ak_live_[a-f0-9]+' ~/.armoriq/credentials.json | head -1)
curl -s -X POST https://staging-api.armoriq.ai/iap/sdk/enforce \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"tool":"test","arguments":{},"intent_token":{"plan":{"goal":"x","steps":[]}}}' | head -c 200

Should return a real policy decision, not a 401.

Copilot routes around a single-tool deny

If you deny web_fetch and Copilot uses shell + curl instead, that's expected. See Policy Rules: Writing effective policies. Write broader rules.

Audit rows aren't showing up in the dashboard

Two possible causes:

1. No API key configured. ArmorCopilot requires credentials. Set api_key in plugin userConfig OR run armoriq-dev login --product armorcopilot to restore the connection.
2. Backend unreachable. The WAL holds rows until connectivity returns. Check ls ~/.copilot/armorcopilot/audit/. If audit.wal is growing but archive is empty, the flusher cannot reach the backend.

Manually flush by restarting Copilot. The MCP server's flusher tick runs every 5s.

"Bad signature" / HMAC errors

These are usually on the ArmorCopilot-MS path (Microsoft Copilot Studio variant), which was parked. If you see them in ArmorCopilot (GitHub Copilot CLI), file an issue with the full log. They should not happen.

Reset to a clean state

If nothing else works, wipe everything and reinstall:

# Uninstall + clear all state
copilot plugin uninstall armorcopilot 2>/dev/null
copilot plugin marketplace remove armorcopilot 2>/dev/null
rm -rf ~/.copilot/installed-plugins/armorcopilot
rm -rf ~/.copilot/armorcopilot
rm -rf ~/.armoriq/armorCopilot
mv ~/.armoriq/credentials.json ~/.armoriq/credentials.bak.$(date +%s) 2>/dev/null

# Reinstall fresh
curl -fsSL https://armoriq.ai/install_armorcopilot.sh | bash

Filing a bug

RECENT_LOG=$(ls -t ~/.copilot/logs/*.log | head -1)
copilot --version > /tmp/armorcopilot-bug.txt
node --version >> /tmp/armorcopilot-bug.txt
copilot plugin list >> /tmp/armorcopilot-bug.txt
grep -E "armorcopilot|hook=" "$RECENT_LOG" | tail -50 >> /tmp/armorcopilot-bug.txt
echo "---" >> /tmp/armorcopilot-bug.txt
ls -la ~/.copilot/armorcopilot/ >> /tmp/armorcopilot-bug.txt 2>&1
cat /tmp/armorcopilot-bug.txt

Paste the output into a GitHub issue at https://github.com/armoriq/armorCopilot/issues.