Skip to main content
Solutions to problems you might encounter when using Catty.

​
Authentication Issues

Error: Not logged in. Run 'catty login' to authenticate.Solution: Run catty login to authenticate. If you’ve already logged in, your credentials may have expired.
catty login
Error: missing authorization headerCauses:
  • CLI isn’t sending the auth token
  • Outdated CLI version (npm may have cached an old binary)
Solutions:
  1. Verify you’re logged in: cat ~/.catty/credentials.json
  2. Re-login: catty login
  3. Update the CLI: npm update -g @diggerhq/catty
Error: 502 Bad Gateway errors when creating sessionsCause: API redeployment may invalidate some tokensSolution: Re-authenticate:
catty logout
catty login
Error: Authentication failsCause: Server-side configuration issueSolution: This is likely a temporary service issue. Try again in a few minutes. If it persists, report the issue.

​
Connection Issues

Symptom: Terminal disconnects after being idleExpected behavior: Catty sends keepalive pings every 25 seconds to prevent thisSolutions:
  1. Reconnect with catty connect <label>
  2. Check your network connection
  3. If persistent, report the issue with your network setup details
Error: Unable to establish WebSocket connectionCauses:
  • Network firewall blocking WebSocket
  • Proxy server interfering
  • Session machine not ready
Solutions:
  1. Wait a few seconds and try again
  2. Check if your network allows WebSocket connections
  3. Try from a different network
Error: Session with label xyz not foundCauses:
  • Session was stopped
  • Session TTL expired
  • Typo in label
Solutions:
  1. Run catty list to see available sessions
  2. Create a new session with catty new

​
Workspace Issues

Symptom: Claude doesn’t see your uploaded filesCauses:
  • Upload failed silently
  • Files excluded by .gitignore
  • Upload size exceeded
Solutions:
  1. Check CLI output for “Workspace uploaded” confirmation
  2. Review your .gitignore - files matching patterns aren’t uploaded
  3. Ensure workspace is under 100 MB
  4. Try catty new again
Error: Workspace exceeds 100 MB limitSolutions:
  1. Add large files/directories to .gitignore: 
    # .gitignore
dist/
build/
*.zip
large-data/
  2. Use --no-upload and clone your repo in the session: 
    catty new --no-upload
# Then in Claude: git clone https://github.com/...
Symptom: Changes Claude makes don’t appear locallyCauses:
  • --no-sync-back flag was used
  • WebSocket disconnected
  • File outside /workspace
Solutions:
  1. Reconnect without --no-sync-back: catty connect <label>
  2. Ensure Claude is editing files in /workspace
  3. Check that you’re in the correct local directory
Symptom: Synced files appear in unexpected placesCause: You’re in a different directory than when you created the sessionSolution: Navigate to the original directory before reconnecting:
cd /path/to/original/directory
catty connect <label>

​
Claude Code Issues

Symptom: Claude Code asks you to log inExpected behavior: This should be pre-configured and shouldn’t happenSolution: This is a bug. Report it with the exact prompt you see.
Symptom: Claude asks to approve API keyExpected behavior: The API key should be pre-approvedSolution: This is a bug. The wrapper script should handle this. Report the issue.
Symptom: Claude reports missing toolsCause: Possibly using an outdated executor imageSolution: This is a server-side issue. The executor should have all tools pre-installed. Report the issue.

​
Billing Issues

Error: Monthly token quota exceededSolutions:
  1. Upgrade to Pro when prompted
  2. Wait for monthly quota reset
  3. Check when your quota resets (beginning of billing cycle)
Symptom: Browser opens but Stripe checkout failsSolutions:
  1. Try a different browser
  2. Disable browser extensions that might block Stripe
  3. Check your network connection
Symptom: Paid for Pro but quota error persistsCause: Webhook may be delayedSolutions:
  1. Wait a few minutes for webhook processing
  2. Try catty new again
  3. If persistent, contact support with your payment confirmation