Troubleshooting

"ArmorGemini intent plan missing for this session"

Cause: Gemini did not call register_intent_plan before using a tool. This happens when the plan expired or the session just started.

Fix: Re-prompt. Gemini will register a new plan on the next turn.

"ArmorIQ intent token expired"

Cause: The intent token TTL (10 minutes by default) expired before Gemini finished executing. Most prompts finish well within this window, but very long multi-step plans with extended thinking time can hit it.

Fix: Restart your prompt. Gemini will register a fresh plan. The plugin auto-refreshes tokens at the turn boundary, so this should rarely surface in practice.

If you need to extend the TTL for a long-running workflow, edit scripts/lib/config.mjs in the ArmorGemini install directory and raise validitySeconds above the current 600s default, for example 900 (15 min).

"ArmorGemini intent drift: tool not in plan"

Cause: Gemini tried to use a tool it did not declare in its plan.

Fix: This is working correctly. Intent drift detection is blocking an unplanned tool. Gemini should re-register a plan that includes the tool, which it usually does automatically on retry.

"Policy denied path /steps/[0]/tool"

Cause: The ArmorIQ backend's policy is denying tool calls at token issuance time. This happens when your ArmorIQ tenant has blocking policies with no allow-rules.

Fix: Configure allow-rules in your ArmorIQ tenant dashboard at https://platform.armoriq.ai.

Hooks do not fire on gemini start

Cause 1: The hook block is missing from ~/.gemini/settings.json.

Fix: Re-run the installer:

curl -fsSL https://armoriq.ai/install_armorgemini.sh | bash

Cause 2: The command: path points to a non-existent hook-router.mjs.

Fix: Confirm the ArmorGemini checkout exists at the path referenced in the hooks:

grep armorGemini ~/.gemini/settings.json
ls -la ~/.armoriq/armorGemini/scripts/hook-router.mjs

If the checkout is gone, re-clone it:

git clone https://github.com/armoriq/armorGemini ~/.armoriq/armorGemini

Cause 3: Gemini CLI is caching an older settings.json. Some Gemini CLI builds do not reload settings mid-session.

Fix: Fully quit gemini and reopen. If that fails, run gemini --config-path to confirm which settings file is actually being read.

/armor:* commands do nothing

Cause: TOML files were not copied into ~/.gemini/commands/armor/.

Fix:

ls ~/.gemini/commands/armor/
# expect: add.toml, help.toml, list.toml, template.toml

If missing, re-run the installer, or copy them from ~/.armoriq/armorGemini/.gemini/commands/armor/.

armoriq: command not found after install

Cause: Global npm install failed (permissions issue).

Fix:

npx @armoriq/sdk login --product armorgemini

Or fix permissions:

sudo npm install -g @armoriq/sdk

Backend calls are failing (403 / 401)

Cause: The API key is missing, invalid, or the SDK is reading from a different location than you set.

Fix:

armoriq whoami

If that reports "not logged in":

armoriq login --product armorgemini

If it reports the wrong account, clear credentials and re-login:

armoriq logout
armoriq login --product armorgemini

Debug Mode

To see what ArmorGemini is doing:

export ARMORGEMINI_DEBUG=true
gemini

Debug output goes to stderr. You will see hook events, plan registration details, POST /iap/verify-step results, and audit calls.