# 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](/agentpay-sdk/workflows/policy.md#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:

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

If they differ, update the chain profile:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](/agentpay-sdk/workflows/reset-and-uninstall.md) for a clean-slate path. For the main product flow, return to [Workflows](/agentpay-sdk/workflows.md).

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:

```bash
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](/agentpay-sdk/workflows.md). To start fresh, see [Reset and uninstall](/agentpay-sdk/workflows/reset-and-uninstall.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.worldlibertyfinancial.com/agentpay-sdk/workflows/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.