Errors and recovery

icLens presents an error title and short summary, with guidance and technical details under Details. Read the operation and target context before deciding whether to retry. The same transport interruption has different consequences for a status read and a submitted payment.

Current error codes

Code	Meaning and next step
CONTROLLER_DENIED	The caller lacks required target authority. Check the full target principal and operation route; correct access before retrying.
LOGS_GATEWAY_REJECTED	The log gateway rejected the request. Inspect Details for the rejection and effective endpoint.
LOGS_CANISTER_NOT_FOUND	The log request could not locate the target in this network context. Verify principal and network.
LOGS_CANISTER_STOPPED	The log request was rejected for stopped-canister state. Inspect lifecycle and access before deciding whether starting is appropriate.
AGENT_UNREACHABLE	icLens could not establish the Agent read. Check network, endpoint, and reachability.
AGENT_NOT_FOUND	The selected Agent could not be found in the required context. Verify the connection and principal.
AGENT_ENGINE_NOT_ENABLED	The Agent is reachable but this optional engine is not enabled. An active Admin can enable it in Agent › Storage; automatic read retries do not enable it.
AGENT_INVALID_PRINCIPAL	Correct the Agent identifier before connecting.
AGENT_REJECTED	The Agent rejected the request. Read the bounded reason for role, capability, policy, input, or operational state.
LEDGER_INSUFFICIENT_FUNDS	Recheck the funding account, balance, amount, and required fees.
LEDGER_BAD_FEE	The reviewed fee no longer matches the ledger. Refresh the quote and review the changed transaction.
LEDGER_DUPLICATE	A matching ledger transaction already exists. Reconcile against its original block rather than making another transfer.
LEDGER_TEMPORARY	A temporary ledger condition occurred. Follow the retained workflow’s recovery action; do not assume a payment is absent.
LEDGER_REJECTED	The ledger rejected the request. Read the exact stage and reason.
CMC_REJECTED	The Cycles Minting Canister rejected or could not complete the current stage. Check the original payment/notification evidence.
VALIDATION	Correct the named input; do not bypass the validation with a different workspace or Run as.
STORAGE_UNAVAILABLE	The browser could not access storage. Check browser policy and persistence settings.
STORAGE_QUOTA	The browser storage limit was reached. Preserve a backup before deliberate cleanup.
STORAGE_PARSE	Persisted or imported data could not be parsed. Keep the file and inspect its supported format.
STORAGE_SCHEMA	Data does not match the current strict schema. Unsupported fields and versions are rejected.
STORAGE_REJECTED	Storage validation or a storage operation was rejected. Read Details before replacing data.
UNKNOWN	The failure has no more specific normalized category. Capture the operation context and bounded Details for investigation.

A missing newer Agent API can be an upgrade or repair state. It should not be treated as proof that the Agent is unreachable. Use Agent compatibility to distinguish those conditions.

Decide whether another request is safe

What happened	Next action
A read failed before returning data	Resolve the cause and retry that read; preserve independent last-good evidence
Input was rejected before submission	Correct the input and review the new request
Authority was rejected	Correct identity, role, workspace, network, or controller relationship
A mutation is still accepted or running	Inspect the existing operation; wait for its explicit outcome
A mutation’s response was lost	Reconcile live state and the original receipt or operation record
A financial action is ambiguous	Use the original ledger/CMC/Agent evidence; do not send new funds to test the result

Replica rejections such as IC0207 require operator attention to the reported condition. Repeated automatic requests cannot repair authority or target state.

Verify by operation type

For a settings change, read the exact resulting settings. For code installation, verify the module hash and application behavior. For a snapshot, inspect the live snapshot record; for a restore, check the restored state. For a migration, follow the migration status and then verify target identity and placement.

For funding, a submitted wallet request, ledger block, notification result, Agent receipt, and target balance establish different stages. Use funding receipts and recovery.

Share enough evidence to investigate

Review diagnostics before sharing

Record network, workspace, target, Run as, time, error code, and the operation identifier or public receipt appropriate for the incident. Inspect Details before sharing: logs, arguments, notes, and context may contain private application data. Do not share identity delegations, wallet credentials, or notification secrets.

For symptom-led guidance, use Troubleshooting.