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
• Local models: on home hardware a large prompt can take minutes before the first word appears. TatsuCode waits up to 10 minutes for the reply to start, then the usual timeout applies

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

Unity Isn't Answering

When TatsuCode can see why, it tells you:

• Unity is in Safe Mode. Scripts don't compile, so Unity started without the bridge. TatsuCode quotes the compile errors; ask the agent to fix them, then connect again.
• A dialog is open in Unity. TatsuCode quotes its title, message, and buttons. Answer it in Unity; the agent never answers it for you. A command that ran into the dialog runs once you've answered.
• Unity is in the background. Unity only picks up changed files while its window is active. If TatsuCode asks you to, click into Unity once.

See Game Engine Plugins.

Claude Code Sonnet 5.5 or Haiku 5.5 Won't Start

These models need a recent Claude Code CLI: v2.1.284 or later for Sonnet 5.5, v2.1.293 or later for Haiku 5.5. Run claude update in a terminal, then click Refresh in /connect → Claude Code.

Settings Look Reset

If your settings file (config.json in %UserProfile%\.tatsu\) was damaged, for example by a hand edit gone wrong, TatsuCode keeps a copy of it as config.json.corrupt-<date>-<time> and loads your last good settings instead, or the defaults when there's no earlier copy. Nothing is thrown away.

Undo History Missing After Changing Versions

Undo history saved by TatsuCode 1.2 can't be read by older versions, so an older version opens the session without it. Finish any undos before going back to an older version. TatsuCode 1.2 leaves an undo history saved by a newer version untouched. See File History.

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