Troubleshooting

Docs / Troubleshooting

Resolve the most common IAP failures

In the current beta, most user-visible failures come from one of these categories: install problems, wrong registry settings, missing credentials, exhausted quota, or sequence mismatch.

Start here first

Before changing anything else, run the two standard diagnostics:

iap-agent registry check --json
iap-agent account usage --json

These two commands identify most setup problems quickly. If you cannot run account usage, the registry check output is still useful.

Package install fails

• Confirm you are inside the intended virtual environment.
• Upgrade pip before reinstalling the package.
• Clear the local wheel cache if the install still behaves unexpectedly.

python -m pip install -U pip
python -m pip cache purge
python -m pip install -U iap-agent

Registry is unreachable

This usually means the registry base URL is wrong or your network cannot reach the service.

• Check registry_reachable in iap-agent registry check --json.
• Confirm the configured registry base is the current beta URL.

iap-agent registry set-base --base "https://registry.ia-protocol.com"
iap-agent registry check --json

No usable local identity

If identity_checked is false, the CLI could not load a valid local identity.

• Create a fresh project-local identity if this should be a new agent.
• Use the correct workspace before retrying issuance.

iap-agent init --project-local --show-public --json
iap-agent registry check --json

Missing or invalid registry API key

If the registry API key is missing, issuance may fall back to payment. If it is invalid, issuance requests can fail directly.

iap-agent registry set-api-key --api-key "<API_KEY>"
iap-agent registry check --json

If the key still fails, ask the operator for a replacement key.

Missing or invalid account token

If the account token is missing or invalid, iap-agent account usage --json will fail and account_token_valid may be false in registry check.

iap-agent account set-token --token "<ACCOUNT_TOKEN>"
iap-agent account usage --json

If the token is invalid, ask the operator to issue a fresh account token.

Quota is exhausted

In beta, issuance is blocked when the available quota is exhausted.

• Inspect the remaining values in iap-agent account usage --json.
• Ask the operator whether a quota increase, add-on, or plan change is appropriate.
• Do not assume the system will silently move you to a higher paid tier.

Continuity request fails with a sequence mismatch

• Inspect the registry-side state for the current agent_id.
• Compare the registry sequence with your local AMCS state.
• If this should be a separate agent, create a fresh project-local identity instead of reusing the old one.

iap-agent registry status --identity-file ./.iap/identity/ed25519.json --json
iap-agent amcs root --project-local --amcs-db ./amcs.db --json

Verification fails

• Confirm you are verifying the correct certificate bundle file.
• In strict mode, provide the saved identity anchor.
• Use the correct trusted registry public key if you are pinning it manually.

iap-agent verify ./continuity_record.json --registry-base "https://registry.ia-protocol.com" --json
iap-agent verify ./continuity_record.json --profile strict --registry-public-key-b64 "<REGISTRY_PUBLIC_KEY_B64>" --identity-anchor ./identity_anchor.json --json

When to escalate

Escalate when the registry is reachable but behaves inconsistently, verification succeeds on clearly tampered data, or you suspect credentials were leaked.

Support and upgrade questions: admin@ia-protocol.com