Troubleshooting
Sign-in, intent, policy, installation, and telemetry issues
Troubleshooting
These instructions use the armorclaude@armoriq plugin and the armoriq CLI.
Installed but Not Connected
ArmorClaude starts in monitor mode when no usable armorclaude login exists for the selected backend. Tool calls are not checked against an intent plan, but local policy rules still apply.
armoriq login --product armorclaude
armoriq whoamiA login for another product does not replace the ArmorClaude profile. ARMORIQ_API_KEY and the old API-key plugin field are not used.
If the notice says the saved key was ignored, sign in again to replace the unusable credential.
Nothing Is Blocked
A signed-in ArmorClaude follows the workspace mode on the Monitor page, and a new workspace starts in Quiet. In Quiet and Show in chat every call runs, and the calls your policy would have blocked or held are listed on that page.
To block, a workspace admin sets Tool calls in the chat to Block, or gives you your own mode in the Teammates card. The change applies from the next session. To block on one machine whatever the workspace says, set ARMORIQ_ORG_MODE=enforce. See Workspace Mode.
Intent Plan Missing or Intent Drift
When a restrictive policy enables intent enforcement, a call that changes state needs a registered plan. A call outside that plan is blocked.
Ask Claude to register or revise its plan and retry. A read succeeding without a plan does not demonstrate a failure: Read, Grep, Glob, WebSearch, and WebFetch need no plan, but still pass policy checks.
A policy with default allow and only permit statements, such as all-allow, records plans without blocking missing plans, drift, or expiry. An empty default-deny policy does not qualify. Use a restrictive policy when you want those controls.
Intent Token Expired
The configured token lifetime is 3600 seconds. ArmorClaude attempts refresh near expiry during tool checks and at the turn boundary. If the backend is unavailable or refresh fails, Claude may need to register a fresh plan.
Check your network and saved login if this repeats. ARMORCLAUDE_VALIDITY_SECONDS is not read; setting it does not change the token lifetime.
Backend Policy Denies a Plan
A local allow rule does not override an organization policy checked by the backend. Review the organization's policy in the ArmorIQ console, or ask the organization owner to permit the required action.
Step verification and policy binding are separate features. Remote CSRG step verification is not always enabled merely because you are signed in; the current configuration enables it in local mock mode. See Concepts.
Hook Errors or Incomplete Installation
Check the installed plugin and prerequisites:
claude plugin list
node --version
git --versionUse Node.js 20.19 or newer, npm, and Git. To repair or update the installation, run the installer again:
curl -fsSL https://armoriq.ai/install_armorclaude.sh | bashRestart Claude Code afterwards. Enable debug output below if the hook still fails.
Plugin Not Found in the Marketplace
Refresh the marketplace and install the plugin:
claude plugin marketplace update armoriq
claude plugin install armorclaude@armoriqIf fetching the marketplace fails, check the reported network or repository-access error. Do not change repository visibility to work around an installation error.
Policy Commands Show No Feedback
Check the active policy and any staged proposal:
/armorclaude:armor policy listA staged change is not active until you confirm it with /armorclaude:armor yes. If command feedback is missing in Desktop, inspect the policy before assuming the change succeeded, then restart the app if it is using cached plugin files.
CLI Works but Desktop Uses an Older Plugin
Quit Claude Desktop completely and reopen it. Check that the plugin is installed and enabled in the Code environment. CLI and Desktop can cache plugin files separately.
armoriq Command Not Found
The global SDK install may have failed. Use its CLI through npx:
npx @armoriq/sdk login --product armorclaudeOr fix npm permissions and install the CLI with npm install -g @armoriq/sdk.
Missing Traces or Token Usage
Check the saved login, selected backend, and plugin telemetry settings. disable_observability disables both traces and token usage; disable_usage_sync disables only usage sync.
Look for worker and telemetry delivery diagnostics in the active variant's data directory. Queued data may be waiting for a telemetry policy lease or retry. Delivery has no fixed five-second guarantee.
See Observability for the session lifecycle and Observability Troubleshooting for dashboard checks.
Debug Mode
export ARMORCLAUDE_DEBUG=true
claudeDiagnostics go to stderr. Review logs for credentials or personal information before sharing them.
For help, see https://github.com/armoriq/armorClaude or email license@armoriq.io.