Troubleshooting

This page covers common error messages and symptoms from the AgentPay SDK and how to resolve them.

Policy denial messages

For policy rejection messages and their meanings, see Policy rejection messages.

Daemon socket errors

Symptom: connection refused or no such file or directory for the daemon socket.

Possible causes:

• The daemon is not running - rerun agentpay admin setup to install and start it

• The socket path was changed or removed - check with agentpay config show --json

• A reset or uninstall removed the daemon - run setup again

Default socket path: /Library/AgentPay/run/daemon.sock

Vault password lockout

Symptom: Repeated authentication failed errors followed by a silent 30-second pause.

Cause: The daemon locks out admin authentication after 5 consecutive failed attempts for 30 seconds.

Fix: Wait 30 seconds and retry with the correct vault password. If you have forgotten the vault password and have an encrypted offline backup, restore it with agentpay admin setup --restore-wallet-from <backup.json>. If you have no backup, the only recovery path is agentpay admin reset, which discards the current wallet state.

RPC chain ID mismatch

Symptom: chain id mismatch or unexpected transaction failures.

Cause: The configured RPC URL returns a different chain ID than the one saved in your chain profile.

Fix: Verify the RPC URL matches the expected chain:

agentpay rpc chain --rpc-url <YOUR_RPC_URL> --json
agentpay admin chain list --json

If they differ, update the chain profile:

agentpay admin chain switch <CHAIN_KEY> --rpc-url <CORRECT_RPC_URL> --save --json

Gas estimation failure

Symptom: gas estimation failed or insufficient funds for gas.

Possible causes:

• The wallet does not have enough native gas token for the transaction

• The RPC endpoint rejected the eth_estimateGas call

• The transaction would revert on chain

Fix:

1. Check native balance: agentpay rpc balance --address <ADDRESS> --rpc-url <RPC_URL> --json

2. Fund the wallet with native gas if needed

3. If using broadcast, try setting --gas-limit explicitly

Receipt polling timeout

Symptom: receipt timeout after broadcasting.

Cause: The CLI waits up to 30 seconds for an on-chain receipt. A timeout does not mean the transaction failed - it may still be pending in the mempool.

Fix:

• Check manually: agentpay rpc receipt --hash <TX_HASH> --rpc-url <RPC_URL> --json

• Use --no-wait to skip receipt polling if you prefer to check later

• If the transaction is stuck, it may need a higher gas price - resubmit with --max-fee-per-gas-wei

Deprecated admin bootstrap command

Symptom: unknown command: admin bootstrap or similar.

Cause: The standalone admin bootstrap command was removed. Bootstrap functionality is now integrated into agentpay admin tui (Bootstrap view) and agentpay admin setup --attach-bootstrap-policies.

Fix: Use the TUI or setup flags instead:

agentpay admin tui          # go to Bootstrap view
agentpay admin setup --attach-bootstrap-policies

Vault password input blocked

Symptom: insecure --vault-password is disabled or AGENTPAY_VAULT_PASSWORD is disabled for security.

Cause: The --vault-password flag and AGENTPAY_VAULT_PASSWORD environment variable are intentionally blocked.

Fix: Use --vault-password-stdin for non-interactive environments:

echo "$VAULT_PASSWORD" | agentpay admin setup --vault-password-stdin

Or use the interactive TTY prompt (default behavior).

Status and repair

Before investigating further, run agentpay status to get a snapshot of wallet, daemon, and credential health:

agentpay status --json

Key flags:

• --strict - exits with code 1 on warnings (useful in CI)

• --json - machine-readable output

What status checks

The status command inspects every layer of the wallet runtime and reports issues as warnings:

Area	What is checked
Config	config.json exists and is parseable
Agent key ID	agentKeyId is present and is a valid UUID
macOS Keychain	Agent auth token is stored for the configured agent key ID
Legacy config token	agentAuthToken is not still present in config.json
Active chain	chainId, chainName, and rpcUrl are configured; RPC URL passes trust validation
Chain profiles	Every saved chain profile has a trusted RPC URL
Bootstrap artifacts	Scans ~/.agentpay/bootstrap-*-*.json for plaintext secrets, expired leases, or untrusted files
Daemon socket	Default /Library/AgentPay/run/daemon.sock exists and passes file system trust checks
State file	/var/db/agentpay/daemon-state.enc exists and passes trust checks
Rust binaries	agentpay-daemon, agentpay-admin, agentpay-agent are installed and trusted

Status returns a ready boolean and a warnings[] array. When --strict is set, any warning causes exit code 1.

What repair fixes

If status reports fixable issues, run agentpay repair to automatically fix common problems:

agentpay repair --json

Repair performs two main actions:

1. Legacy agent auth migration - moves agentAuthToken from config.json into macOS Keychain, then scrubs the plaintext entry from config. This is the same operation as agentpay config agent-auth migrate.

2. Bootstrap artifact cleanup - deletes or redacts auto-generated bootstrap-*-*.json files in ~/.agentpay/ that still contain plaintext secrets.

If problems persist, see Reset and uninstall for a clean-slate path. For the main product flow, return to Workflows.

Repair flags:

• --agent-key-id <id> - target a specific agent key

• --overwrite-keychain - force re-import of agent auth into Keychain even if Keychain already holds a different token

• --redact-bootstrap - redact plaintext bootstrap output files instead of deleting them

• --strict - fail on warnings

• --json - machine-readable output

Repair output includes a before/after status comparison with fixedWarnings, remainingWarnings, and newWarnings.

If the issue persists after repair, consider agentpay admin reset followed by a fresh setup.

Deprecated agent auth commands

Symptom: use config agent-auth rotate or use config agent-auth revoke error when running agentpay admin rotate-agent-auth-token or agentpay admin revoke-agent-key.

Cause: These standalone admin passthrough commands are blocked. Agent auth lifecycle commands have moved to the config agent-auth subcommand group.

Fix: Use the new commands:

agentpay config agent-auth rotate    # instead of admin rotate-agent-auth-token
agentpay config agent-auth revoke    # instead of admin revoke-agent-key

For the main product flow, return to Workflows. To start fresh, see Reset and uninstall.