Troubleshooting

BudgetExceededError on store

Cause: projected spend exceeds configured maxSpendUSDFC.

Fix:

• increase maxSpendUSDFC intentionally
• reduce replication/TTL requirements
• lower write frequency for non-critical payloads

StorageDealFailedError

Cause: provider write path failed (network, provider, or deal execution issue).

Fix:

• verify provider health and credentials
• inspect payload shape/size in your app logs
• retry with exponential backoff
• fail over to reduced policy for non-critical workloads when acceptable

InsufficientBalanceError

Cause: wallet cannot cover operation cost.

Fix:

• ensure Vincent and funding route are configured
• check source-chain balances
• verify route bridge prerequisites in your environment

FundingTimeoutError

Cause: expected wallet funding did not arrive in configured window.

Fix:

• verify bridge route execution and confirmations
• inspect upstream chain congestion
• increase timeout only after route-level diagnosis
• alert and pause non-critical writes

Delegation Verification Fails

Cause: recipient mismatch, token expiration, or signature issues.

Fix:

• verify caller DID passed to verifyDelegation
• issue a new token with fresh TTL
• ensure token CID is the one returned by delegate

PruneError

Cause: index mutation/logging failure during prune.

Fix:

• retry prune on same CID
• verify log path write permissions
• check runtime memory/index health in host process

Retrieval/Decryption Problems

Cause: corrupted payload metadata, wrong keys, or provider failure.

Fix:

• validate CID exists in active index
• confirm encryption path/key config consistency
• retry retrieval and inspect provider status

MCP Server Not Reachable

Cause: process not running, wrong port, or config mismatch.

Fix:

• run npx @engram-sdk/mcp
• probe with curl http://localhost:3456/health
• confirm MCP client uses same URL/path

Fast Triage Checklist

1. capture exact error class and code
2. capture CID or token CID involved
3. capture provider + network
4. capture budget state (runningSpendUSDFC, maxSpendUSDFC)
5. confirm recent config/deploy changes