ArmorClaudeTroubleshooting

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 whoami

A 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 --version

Use 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 | bash

Restart 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@armoriq

If 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 list

A 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 armorclaude

Or 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
claude

Diagnostics go to stderr. Review logs for credentials or personal information before sharing them.

On this page