Troubleshooting

This guide focuses on safe, user-level recovery steps without exposing internal implementation details.

Fast Recovery Checklist

1. Press Escape to stop the current operation
2. Try a different model with /models
3. Re-check provider connection with /connect
4. Use /compact for long sessions
5. Start fresh with /new

Common Issues

API Key or Provider Error

Try:

/connect

Then:

• Re-enter credentials
• Test connection
• Switch provider/model if needed

Model Not Responding

• Retry once
• Switch to another model
• Start a fresh session with /new
• Check provider status from your account dashboard

Rate Limit / Quota Reached

Use:

/usage
/usage-quota

Then:

• Wait and retry
• Use a different model/provider
• Reduce request size

OAuth Connection Fails

• Disconnect and reconnect from /connect
• Complete sign-in promptly
• Retry from a clean browser session

Local Provider Not Reachable

• Ensure local model server is running
• Re-check configured endpoint in /connect
• Verify local networking/firewall policy

Slow Responses

• Use a faster model
• Reduce prompt size
• Compact long session history
• Start a fresh session for unrelated tasks

Response Truncated or Cut Off

• Ask the model to continue
• Split task into smaller requests
• Use a model with larger context window
• Compact context when needed

Edit Could Not Be Applied

• Ask TatsuCode to re-read the file
• Provide a bit more surrounding context
• Retry with a narrower request

Permission Denied / Action Blocked

• Confirm file/folder access
• Check permission policy via /permissions
• Retry with explicit user approval

UI Feels Stuck

• Press Escape
• Wait for active operation to end
• Start /new
• Restart app if needed

Performance Tips

• Keep sessions focused by topic
• Compact periodically during long runs
• Prefer smaller/faster models for iterative work
• Save major milestones using named sessions

Data and Security Hygiene

• Don’t share sensitive screenshots/logs publicly
• Keep credentials.enc private
• Rotate keys if compromise is suspected
• Disconnect providers you no longer use

When to Escalate

If issues persist after the checklist:

1. Capture the exact error text
2. Record the command/prompt that triggered it
3. Note your TatsuCode version
4. Reproduce in a minimal test scenario

Next Steps

• Providers — connection setup help
• Settings — behavior tuning
• Commands — all available commands
• Data & Privacy — privacy and local data controls