Skip to main content

​
zkID Issues

1. “Failed to create zkID” Cause: Database connection issue or username already exists. Solutions:
  1. Check if username is unique
  2. Verify you’re connected to the internet
  3. Try again in a few seconds
2. “On-chain verification failed” Cause: Insufficient SOL balance or network congestion. Solutions:
  1. Check wallet balance - need ~0.01 SOL for gas
  2. Wait for network congestion to clear
  3. Try with zk id login --blockchain solana
3. “Proof generation timeout” Cause: Heavy computational load on server. Solutions:
  1. Wait a few seconds and retry
  2. Try during off-peak hours
  3. Check your internet connection
4. “User has no identity public key” Cause: Account created before cryptographic proofs were enabled. Solution: Re-register with zk id register to enable cryptographic proofs.

​
zkStorage Issues

5. “File upload failed” Possible causes:
  • File too large (limit: 100MB)
  • IPFS gateway timeout
  • Not logged in
Solutions:
  1. Check file size - must be under 100MB
  2. Make sure you’re logged in with zk id login
  3. Try again - automatic retry is built in
6. “Decryption failed” Cause: Wrong password or corrupted file. Solutions:
  1. Double-check password (case-sensitive)
  2. Verify the file ID is correct
  3. Check file integrity with checksum
7. “IPFS gateway timeout” Cause: IPFS network congestion or file not yet propagated. Solutions:
  1. Wait 30 seconds and retry
  2. System automatically tries multiple gateways (Pinata, Cloudflare, ipfs.io)
  3. Check if file exists with zk storage info <file-id>

​
zkCompression Issues

8. “Compression failed” Cause: Insufficient SOL balance or RPC issues. Solutions:
  1. Check SOL balance with zk tokens
  2. Need at least 0.005 SOL for compression fees
  3. Wait and retry if RPC is congested
9. “Balance not updating after compression” Cause: Light Protocol RPC indexer sync delay. Solutions:
  1. Wait 30-60 seconds for indexer to sync
  2. System automatically polls for updates
  3. Run zk tokens to refresh balance
10. “Decompression stuck” Cause: Light Protocol RPC timeout or indexer delay. Solutions:
  1. Wait 2-5 minutes for confirmation
  2. Check transaction on Solana Explorer
  3. System uses automatic retry polling

​
Starknet Issues

11. “This proof has already been submitted to the blockchain” Cause: Attempting to submit duplicate proof. Solution: Each proof can only be submitted once. Check existing proofs with zk id status. 12. “Server wallet has insufficient STRK” Cause: Server wallet needs STRK for gas sponsorship. Solution: Contact zkTerm team - this is a server-side issue that needs admin attention. 13. “Invalid proof hash format” Cause: Proof data is malformed. Solutions:
  1. Regenerate the proof with zk id prove
  2. Make sure you’re using the latest version
14. “Starknet not configured” Cause: Missing environment variables for Starknet. Solution: This is a server configuration issue. Contact support. 15. “Transaction failed with status: REVERTED” Cause: Smart contract rejected the transaction. Solutions:
  1. Check if proof already exists on-chain
  2. Verify zkID format is correct
  3. Try again with fresh proof

​
HoudiniSwap Issues

16. “HoudiniSwap API error” Cause: External API rate limit or service issue. Solutions:
  1. Wait a few minutes and retry
  2. Check swap status with zk swap --houdini status <id>
  3. View history with zk swap --houdini history
17. “Quote expired” Cause: Swap quotes are time-limited. Solution: Get a new quote with zk swap --houdini quote <from> <to> <amount>

​
API Integration Issues

18. “401 Unauthorized” Cause: Not logged in or session expired. Solutions:
  1. Login first via terminal or API
  2. Include credentials in fetch requests:
fetch('/api/auth/me', {
  credentials: 'include'
});
19. “CORS error” Cause: Frontend making requests without proper credentials. Solution: 
fetch('/api/endpoint', {
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' }
});
20. “Rate limit exceeded (429)” Cause: Too many requests in short time. Solutions:
  1. Implement exponential backoff
  2. Cache responses when possible
  3. Batch requests where possible

​
Terminal Issues

21. “Command not found” Cause: Typo or command doesn’t exist. Solutions:
  1. Type zk help to see all commands
  2. Check spelling carefully
  3. Commands use format: zk <category> <action>
22. “Terminal not responding” Cause: Browser memory issue or connection lost. Solutions:
  1. Refresh page (Cmd/Ctrl + R)
  2. Clear browser cache
  3. Try incognito/private mode

​
Common Error Codes

CodeMeaningSolution
400Bad RequestCheck request parameters
401UnauthorizedLogin first with zk id login
403ForbiddenInsufficient permissions
404Not FoundVerify file/endpoint exists
429Rate LimitedWait and retry
500Server ErrorReport to team

​
API Endpoints Reference

EndpointPurpose
/api/auth/*zkID authentication
/api/light/*Compression operations
/api/storage/*File storage
/api/zk-toolkit/*Cryptographic primitives
/api/starknet/*Starknet operations
/api/bridge/*Cross-chain bridge

​
Debugging Tips

Check Browser Console Open DevTools (F12) → Console tab to see error details. Verify Transaction Status For Solana transactions, check Solana Explorer. For Starknet transactions, check Starkscan. Check zkID Status 
zk id status
Shows verification status on both Solana and Starknet.

​
Getting Help

If your issue isn’t listed:
  1. Check browser DevTools console for error details
  2. Ask on Twitter: @zkterm
  3. Report bugs: github.com/zkterm
  4. Use zk bug report in terminal to submit a report