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

Project Folder Rejected

TatsuCode refuses to create or open projects in folders that could damage Windows if the agent makes a mistake — system directories, drive roots, Program Files, the Windows folder, etc. If a project folder is rejected:

• Move the project to a non-system location (e.g. ~/projects/, C:\Source\)
• Use a subfolder rather than a drive root
• These guardrails stay on even in YOLO mode by design

TatsuCode Stole Focus / Window Wouldn't Stay Foreground

Fixed in v0.9.107 — TatsuCode no longer steals focus, and chimes/badges don't grab the active window. If you still see this, restart the app.

Crash Recovery

If TatsuCode crashes or your machine loses power mid-session, the session is now resilient — long sessions are saved frequently and restore cleanly on next launch. If something does go wrong, a detailed crash log is captured to make debugging easier.

Crash log location: %LocalAppData%\Tatsu.AI\TatsuCode\<version>\logs\

When asking for support, attaching the most recent crash log is the fastest way to diagnose the issue.

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