Troubleshooting
Common issues, what they mean, and how to fix them.
Wallet API errors
The wallet lane maps STRK20 Wallet API failures to honest messages. The common codes:
| Code | Meaning | Fix |
|---|---|---|
118 | Not registered for private STRK20 | Enable private receiving; the wallet transparently registers your viewing key. |
119 | Insufficient private balance | Shield more funds before sending. |
120 | Action could reveal private state | The wallet rejected the request to protect privacy — adjust the request. |
113 | You rejected the operation | Re-run the flow and approve in your wallet. |
114 / 163 | Asset not supported by the connected wallet/pool | Use a supported token (STRK, ETH, USDC on Sepolia). |
162 | Wallet API version too old | Update your privacy wallet to Wallet API ≥ 0.10. |
Account finalizing
If a fresh Ready account cannot be proven against yet, the app waits for on-chain finality (~10 blocks) before registration/proving. The error message tells you whether the account is not yet deployed (send it a small amount of Sepolia ETH/STRK via the faucet to activate it) or simply still finalizing (wait a few blocks and retry).
Wrong network
Private STRK20 runs on Starknet Sepolia. If the wallet reports a different chain, the app asks you to switch networks in the wallet (wallet_switchStarknetChain).
Recipient has not enabled private receiving
A private note can only be created for a recipient whose viewing key is registered. Ask the recipient to enable private receiving in a supported privacy wallet first.
Treasury execution refusals
| Symptom | Cause / fix |
|---|---|
| “Analysis expired” | Proposal TTL (120 s) elapsed. Re-run the analysis. |
| “Balances changed” | State moved since analysis. Re-analyze against current balances. |
| “Policy rejected against current state” | Your guardrail fails on fresh state/prices. Adjust the amount or guardrail, or re-analyze. |
| “Fresh live price required” | A volatile asset (STRK/ETH) needs a fresh live AVNU price to authorize execution. Retry when the market feed is available. |
| “Analysis only — no approved destination” | The treasury has no approved private destination. Add one (via your account or the server allowlist) to enable execution. |
AI provider not configured
/api/ai/analyze returns 502 when the AI is not configured (AI_API_KEY/AI_MODEL missing). The treasury still works: portfolio, health, and the deterministic diagnosis run without the LLM. Add the server-onlyAI_API_KEY to .env.local and restart.
Prices unavailable
The analyze endpoint returns 502 if prices cannot be resolved at all. The UI shows an advisory tag when any volatile-asset price is a static fallback rather than a live market price.