Skip to content

FAQ and troubleshooting

My IDE can't connect to AGENSAI

Symptoms: the agent panel doesn't show AGENSAI's tools; chat says "tool not found."

Check, in order:

  1. Is the orchestrator installed? Run agensai status. If it says "not initialized", run npx @agensai/cli install <token> (get a token from the dashboard).
  2. Is the daemon running? Run agensai status. Look for the "Active device" section. If it's null, your IDE hasn't spawned the daemon yet, restart your IDE.
  3. Is there a stale lockfile? If agensai status shows alive: false under "Active device", the lockfile is stale. The next serve will reclaim it. Restart your IDE.
  4. Can your IDE find npx @agensai/cli? Some IDE sandboxes run with a different PATH than your shell. Try installing globally: npm i -g @agensai/cli, then update your MCP config to use agensai serve directly.
  5. MCP config in the right place? See MCP setup for the canonical paths per IDE.

"another agensai daemon is already serving" (exit code 8)

A second serve invocation tried to start while the first is alive. Causes:

  • Two IDEs both have AGENSAI MCP wired and both tried to spawn at once.
  • You ran agensai serve manually while your IDE already had a daemon up.

Fix: stop the active daemon first. Either close the IDE that owns it or run agensai disconnect. agensai status shows the active hostname + pid.

This is intentional, ERC-4337 nonces are per-account, so two daemons signing concurrently would collide.

My orchestrator is offline (or my device is lost)

Two cases:

Device temporarily offline (sleep, no network): nothing to do. When the device comes back, the daemon resumes signing.

Device permanently lost: sign in to the dashboard from any other device with your passkey. Run the rehydration ceremony, main passkey signs the kill-switch sweep + new orchestrator + agent re-grants in one batched ceremony. See Recovery.

The on-chain kill-switch grant means your funds are recoverable as soon as you have your passkey.

"POLICY_VIOLATION" when an agent tries to act

The agent tried to do something outside its grant. Possible causes:

  • Spending more than the grant allows in the current window.
  • Calling a contract not on the whitelist.
  • Calling a function selector outside the grant.
  • Grant has expired.

The on-chain validator is the source of truth. If you got POLICY_VIOLATION, the cap is real. Do not retry blindly.

To extend the grant, use policy_add from your IDE, this revokes + re-grants atomically with the merged bundle. See policy_add.

Today (v0): policy_add returns FEATURE_DEFERRED. Revoke the current agent and create_agent again with the expanded scope. Restored in v0.1.

To start fresh, revoke the current grant and create_agent again with a new policy.

"NAME_TAKEN" when creating an agent

The ENS subname <name>.agensai.eth is already in use somewhere on the namespace. Pick a different name.

Names are global to the agensai.eth namespace, so two AGENSAI users can't both have dca-bot.agensai.eth. Add a personal prefix or differentiator: adrian-dca.agensai.eth, dca-bot-2.agensai.eth.

"RESOLUTION_FAILED" on resolve

ENS has no record for the requested chain. Check:

  • The name actually exists. Try agensai resolve with the default chain first.
  • The chain id is one AGENSAI supports (Base on v0).
  • The agent hasn't been archived (rehydrated under a new orchestrator). Look at the agent's status text record.

Today (v0): revoke is fully enforced onchain, but the agent's status ENS text record stays "active" after revoke. Trust the onchain permission state; trust the status record again in v0.1.

My agent's permissionId changed unexpectedly

Someone (you, or your IDE on your prompting) ran policy_add. Implementation: revoke + re-grant with the merged bundle. The old permissionId is permanently revoked; the new one is what to use going forward.

The lib persists the new id automatically. If you cached the old one in your own code, refresh from get_agent.

Cite: account-api.md lines 181-198, permissions.md line 190.

I revoked an agent. Can I un-revoke it?

No. ERC-7715 revocation is permanent, the permissionId cannot be re-activated. To restore, create_agent with a fresh policy. The ENS subname can be reused if it wasn't released.

Gas is in USDC, why?

JAW supports ERC-20 gas natively. If your orchestrator holds USDC and the user (or your code) selects USDC at signing time, that's what pays gas. AGENSAI runs no paymaster, gas is whatever you fund with.

If you want native ETH gas, fund the orchestrator with a small amount of ETH and select that.

"EIP-1193 4001 / User Rejected"

Standard EIP-1193 error code 4001, the user dismissed a signing prompt. In AGENSAI, this fires only at:

  • Main passkey ceremonies (signup, orchestrator setup, kill-switch sweep, recovery rehydration).
  • Any user-driven biometric event in the dashboard.

The orchestrator and child keys never prompt, they sign locally.

"Unauthorized" / EIP-1193 4100

The wallet isn't connected, or the API key is missing/invalid. Check:

  • AGENSAI_API_KEY is set in your environment (CLI side) or in the dashboard's NEXT_PUBLIC_AGENSAI_JAW_KEY (for the dashboard).
  • The dashboard origin is allowlisted in the JAW Dashboard for that key. See configuration.md line 88.
  • For dashboard sessions, that the user has signed in.

"EXECUTION_REVERTED" but the bundle landed

The bundle was accepted by the validator (the permission check passed) but the inner contract call reverted. Common causes:

  • Insufficient balance (you have spend authority for 50 USDC but only 10 USDC in the orchestrator pool).
  • The contract you called has its own require/revert that fired (slippage, deadlines, allowance, etc.).

Check the recipient contract's revert reason. The validator is satisfied; the failure is downstream.

Where do I see what my agent is actually doing?

Three places:

  • agensai status for the local view.
  • get_agent <ens> from your IDE for an on-chain snapshot of one agent.
  • A block explorer, every agent action is a normal on-chain transaction signed by the agent's smart-account. Look up the SA address.

I want to fork AGENSAI for a different namespace

Fork the repo. Change two things:

  1. The default namespace constant from agensai.eth to your own.
  2. The agensai.xyz references for the dashboard origin.

The architecture (three-tier identity, ENS-records-as-state, kill-switch grant, MCP server) is namespace-agnostic. Most of the code in apps/cli/src/lib/ doesn't know what namespace it's running on.

What chains does AGENSAI support?

v0 ships single-chain on Base (chainId: 8453) and Base Sepolia (84532) for testing. Multi-chain operation is planned for v1+, depends on JAW shipping cross-chain primitives. Your orchestrator's smart-account address is the same on every EVM chain (CREATE2 determinism), so the on-chain identity is portable; only the daemon's runtime is single-chain in v0.

Cite