Troubleshooting

When something goes wrong, the first question is always: where is it breaking? The system has distinct failure zones, and knowing which one you're in saves a lot of time.

flowchart LR
  I["Something broke"] --> A{Where?}
  A -->|"Before wallet prompt"| B["Frontend<br/>route or state issue"]
  A -->|"API error response"| C["Backend<br/>endpoint or auth"]
  A -->|"After wallet signing"| D["Chain<br/>contract state or gas"]
  A -->|"Stuck on pending"| E["Sequencer<br/>indexing or reconciliation"]

---

Wrong page loads after clicking a link

You clicked a link and landed on the wrong tab or a stale view.

What happened: old docs or bookmarks may use outdated ?tab= parameters.

Fix: use these canonical routes:

/agent?v=vault     → Capital OS vault view
/agent?v=oracle    → Capital OS oracle view
/agent?v=brain     → Capital OS brain view
/profile?tab=trust → Profile trust tab

---

401 or 403 on API calls

What happened: the auth header is missing, wrong, or not expected for that endpoint.

Fix:

• For user mutations: include X-Wallet-Address with the Starknet address that matches the target
• For admin endpoints: include a valid X-Admin-Key
• For public/read endpoints: no header needed

One gotcha — not every POST endpoint is wallet-protected. Auth enforcement varies per route. If you're getting a 403 on a route you think should be public, check the API Reference.

---

Contract not deployed / invalid chain error

What happened: your wallet is connected to the wrong network.

Fix: check which surface you're using:

• /portfolio or /passport → your wallet should be on Starknet mainnet
• /agent (Capital OS), /trade (Trade Desk), or proof pipeline features → your wallet should be on Starknet Sepolia

The proof-gated contract system (VaultController, adapters, verifiers) is on Sepolia. Portfolio and passport read mainnet chain state.

---

Deploy flow stuck on "pending"

What happened: the on-chain transaction may have actually succeeded, but the indexer hasn't reconciled yet, or Ekubo downstream services are temporarily slow.

What to do:

1. Check the tx hash on Voyager — if the tx is confirmed on-chain, the operation succeeded regardless of what the UI says
2. Wait 60 seconds and retry the receipt confirm: POST /api/v1/zkdefi/orchestration/receipt/confirm
3. Check backend health: GET /health — if this fails, the backend is down
4. Check sequencer status: GET /api/v1/zkdefi/proofs/sequencer-status

---

Simulation passes but execution fails

This is frustrating because simulation said it would work. A few common causes:

Stale calldata: the market moved between simulation and signing. Re-run simulation with fresh state.

Gate mismatch: your trust context changed (e.g., a session key expired). Check /profile?tab=trust for gate warnings.

Missing adapter metadata: the adapter route for the target opportunity doesn't exist or was updated. Verify the adapter route metadata exists for the opportunity you're trying to execute against.

---

Proof status stuck on "pending"

What happened: the proof was submitted but hasn't settled yet. This could be the sequencer, the settlement path, or just processing time.

What to do:

1. Check sequencer: GET /api/v1/zkdefi/proofs/sequencer-status
2. Check Madara health: GET /api/v1/aggregation/madara/health
3. If both are healthy, the proof may genuinely still be processing — some proofs take 30–60 seconds
4. If the sequencer is unhealthy, the proof will settle once it recovers (proofs are queued, not lost)

---

Chunk or CSS 404 after deploy

What happened: the browser cached old build hashes. After a new build, those hashed filenames no longer exist on the server.

Fix: hard refresh with Ctrl+Shift+R (or Cmd+Shift+R on Mac). This forces the browser to re-fetch everything. If it persists across hard refresh, clear the site cache for zkde.fi entirely.

The build pipeline preserves old chunks during rebuilds to minimize this, but a full clean build can still trigger it.

---

/docs returns 404

What happened: docs weren't synced after the last rebuild.

Fix:

./scripts/sync-docs.sh

This builds VitePress and copies output to frontend/public/docs/. Verify nginx is serving /docs/ from that path — check nginx/zkdefi.conf if you're unsure.

---

WebSocket won't connect

What happened: wrong URL, wrong port, or the backend isn't running.

Fix: the WebSocket endpoint is on the zkde backend (port 8003), not a separate service:

Dev:  ws://localhost:8003/ws/{user_address}
Prod: wss://zkde.fi/ws/{user_address}

Common mistakes:

• Using http:// instead of ws:// (or https:// instead of wss://)
• Forgetting the user address in the URL path
• The backend process isn't running — check pm2 status

For more on WebSocket events: WebSocket Events.

---

Still stuck?

If none of the above helps:

1. Check the backend logs: pm2 logs zkdefi-backend
2. Check the frontend logs: pm2 logs zkdefi-frontend
3. Check nginx error log: tail -f /var/log/nginx/error.log
4. Verify all services are running: pm2 status
5. Check the Architecture page to understand which component handles what