> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zkterm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions

## 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:

```typescript theme={null}
fetch('/api/auth/me', {
  credentials: 'include'
});
```

**19. "CORS error"**

Cause: Frontend making requests without proper credentials.

Solution:

```typescript theme={null}
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

| Code | Meaning      | Solution                       |
| ---- | ------------ | ------------------------------ |
| 400  | Bad Request  | Check request parameters       |
| 401  | Unauthorized | Login first with `zk id login` |
| 403  | Forbidden    | Insufficient permissions       |
| 404  | Not Found    | Verify file/endpoint exists    |
| 429  | Rate Limited | Wait and retry                 |
| 500  | Server Error | Report to team                 |

## API Endpoints Reference

| Endpoint            | Purpose                  |
| ------------------- | ------------------------ |
| `/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](https://explorer.solana.com).
For Starknet transactions, check [Starkscan](https://starkscan.co).

**Check zkID Status**

```bash theme={null}
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](https://x.com/zkterm)
3. Report bugs: [github.com/zkterm](https://github.com/zkterm)
4. Use `zk bug report` in terminal to submit a report