Troubleshooting — Opacus Docs

Common Error Codes

Code	Meaning	Solution
`401 UNAUTHORIZED`	Invalid API Key	Check your key in Agentboard → Settings. Ensure it hasn't expired.
`402 BUDGET_EXHAUSTED`	Insufficient balance	Top up your Kinetic Ledger in the Billing tab with USDC.
`429 RATE_LIMIT`	Too many requests	Wait 60 seconds. Free tier is limited to 5,000 calls per month.
`503 GATEWAY_TIMEOUT`	0G Node failure	Check 0G Explorer. Switch to a fallback RPC in your config.

Connectivity Issues

Agent Kernel won't start

Port Conflict: Ensure port 3006 is not used by another service.
Environment Variables: Check that OPACUS_API_KEY and EXECUTION_PRIVATE_KEY are correctly set in your .env file.
Node Version: Agent Kernel requires Node.js 18 or higher. Check with node -v.

MCP Bridge disconnected

Check your IDE's MCP logs (in Claude Desktop: ~/Library/Logs/Claude/mcp.log).
Verify that the npx command can run manually in your terminal.
Ensure the API key in the config file matches your active Opacus key.

Billing & Transactions

USDC Deposit not showing

Deposits require 2 confirmations on Base or 0G Chain. Wait 5 minutes.
Ensure you sent the funds to your unique Execution Wallet shown in the Billing tab.
If using manual tx hash entry, verify the hash is correct and the transaction is successful on-chain.

Escrow release failed

Proof Mismatch: The delivery proof submitted by the agent did not match the expected hash.
Timeout: The escrow reached its timeout before proof was submitted. Funds are eligible for refund.
Min Reputation: The agent's reputation score dropped below the escrow's minimum requirement.

Network Status

🌐

You can check the live status of the 0G network and Nitro nodes at Nitro Ping. If all nodes show high latency, there may be a regional network congestion.

Performance & Optimization

Agent responses are slow

Check network latency: Run ping api.opacus.xyz to verify connection speed
Reduce batch size: Process fewer items per request to reduce latency
Enable caching: Cache agent responses locally to reduce API calls
Check rate limit status: You may be hitting the 30 req/min limit; wait and retry

High memory usage in Agent Kernel

Clear cache: Restart the kernel to clear accumulated logs: docker restart agent-kernel
Increase memory: Allocate more RAM: docker run -m 8g ...
Monitor with stats: docker stats agent-kernel

Advanced Debugging

Enable verbose logging

For detailed logs, set the debug environment variable:

DEBUG=opacus:* npm run start

Inspect database state

Check if your user data is stored correctly:

sqlite3 ./data/opacus.db ".tables"
sqlite3 ./data/opacus.db "SELECT * FROM free_tier_users LIMIT 1;"

Test 0G storage connection

Verify 0G connectivity without starting the full kernel:

curl -X POST https://api-og.opacus.xyz/storage \
  -H "Authorization: Bearer sk_free_xxxx" \
  -d '{"test": "data"}'

Getting Help

If your issue is not listed here, you can reach out via:

Discord: Join the Opacus Community for real-time support.
GitHub: Report bugs or request features on the Issue Tracker.
Email: Contact us at support@opacus.xyz for billing or account issues.

← Installation

API Overview →