Troubleshooting

Find your symptom below. If none fits, the log file usually says what went wrong.

Tatu says you are not signed in

You can start Tatu with no credential. It tells you to use /login, and a message you send gets an answer like this:

not signed in: run /login (or set an API key such as ANTHROPIC_API_KEY, OPENAI_API_KEY or DEEPSEEK_API_KEY; /login lists every provider)

In print mode, -p, the same problem stops the run:

tatu: provider anthropic: no credential found (set ANTHROPIC_API_KEY, or run `/login anthropic` to sign in with a Claude subscription via OAuth)

Run /login inside Tatu, or export your provider’s variable and start again. A variable that is set wins over a stored credential, so if a sign-in seems to be ignored, check your environment. See Sign in.

GitHub Copilot signs in but a model is missing

After /login github-copilot, /model lists only the models your Copilot account can use. If one is missing, your plan may not include it or your organization may have it turned off in its Copilot settings; ask for it to be enabled, then sign in again so Tatu reads the list again. If the sign-in says Copilot refused the account, check that the GitHub account (or the Enterprise domain you typed) has a Copilot subscription. See Sign in.

GitHub details or publication are unavailable in the app

GitHub CLI is missing or GitHub CLI is signed out refers to gh on the computer running the session, not your phone or model-provider login. Install the GitHub CLI, run gh auth login there, then tap Check again. /login github-copilot does not sign in to this integration.

If commit works but push fails, check that computer’s Git remote and non-interactive Git credentials separately. If GitHub cannot be read, creating a pull request is unavailable even when commit and push work. A later failure does not undo a completed commit or push; read the step results before retrying. See Git and GitHub.

A web preview is missing or opens an error page

Starting a server does not publish it. Ask the agent to show a preview, or run /preview publish <port> [name] in the session’s terminal on the computer running it. The app’s globe appears only when a preview is published and is disabled while disconnected or refreshing. You cannot run /preview from the app.

The app opens / first. If it returns 404 or a server error, fix that route or make it reach the page you want. The startup check reads an HTTP response; it does not verify rendering. For missing API requests or hot reload, publish the additional ports and check your project’s origin and hot-reload configuration. HTTPS previews are not supported. See Web previews.

“interactive mode needs a terminal”

tatu: interactive mode needs a terminal; use -p to run a prompt

Tatu draws an interface, so its input and output must be a terminal. When you pipe into Tatu or run it from a script, use print mode:

tatu -p "Summarize the changes in the last commit"

-p - reads the prompt from standard input. See Scripting.

Find out what happened

Tatu never writes diagnostics on your screen. It writes them to a file:

~/.tatu/logs/tatu.log

The folder is under TATU_HOME if you set that variable. The log records runs, model errors, retries, hooks and background tasks. When it grows past 5 MiB, Tatu moves it to tatu.log.1 and starts a new one. The file is private to your user.

To see more, start Tatu with -debug. The log then also holds every model call (the model and the number of messages) and the arguments of every tool call.

tatu -debug

If the log cannot be opened, Tatu starts anyway and shows the note logging is off: with the reason.

The task paused with “Usage limit”

Your provider reported that the quota is used up. Nothing is lost: choose Try again, Resume at reset (when a time is shown), Switch provider or End task. If no reset is shown, the provider did not give one and /usage could not either; try again later or switch. A billing message means the account needs credit, and no reset applies. A scheduled resume needs the Tatu process to stay open. See Context and cost.

The daemon does not start

The daemon opens sessions on your computer when you ask from the agents list, from another terminal or from the app. Tatu starts it when needed. If it cannot, you see one of these:

the daemon did not answer in <time>: see <path>
the daemon ended as soon as it started: see <path>

The path is the daemon’s own log, ~/.tatu/logs/daemon.log. Read its last lines. For more detail, run the daemon yourself with tatu daemon -debug. See The daemon and worktrees.

An automation did not run

Open tatu automations: each task shows when it runs next and how its last run went.

Nothing happened at the time. Automations run only while the daemon runs. One that Tatu starts for you exits 30 seconds after the last terminal that needs it, so start it yourself and leave it running: tatu daemon -root ~/projects. A repeating task that came due meanwhile runs once when the daemon is back; a task set for one moment runs late by up to an hour, and after that it shows skipped (missed).
skipped (busy). The session of the previous run is still open: it is working, waiting for you, or in the 30 minutes before it closes. A session stopped by a usage limit stays open until you decide what to do with it, and the task is skipped meanwhile. Open it with O.
skipped (full). The daemon already has all the sessions it allows. See The daemon and worktrees.
failed. The session could not start. Select the task and read the reason in the panel beside the list (on a wide terminal), or in ~/.tatu/logs/daemon.log. The project may have moved out of the daemon’s folder, or the model may not be one the computer can use.

See Automations.

The remote connection

Run /remote status in Tatu. The first line is one of these:

It says	It means
`remote: not set up`	You have not run `/remote setup`. Nothing is connected.
`remote: connecting`	Tatu is trying to reach the relay. A reason in parentheses says why it has not worked yet.
`remote: connected`	The session is reachable from your paired devices.
`remote: failed (…)`	The relay refused this connection, and trying again will not change that.
`remote: off`	Set up, but stopped: `/remote start` connects it.

The relay is offline

When the connection drops or the relay cannot be reached, /remote status shows connecting with the reason, and Tatu tries again by itself: after 1, 2, 5 and 10 seconds, then every 30. Your session keeps working; only the remote access waits. Check your network. The log lines that start with remote: give the reason and the next try. When the relay is back, Tatu reconnects without your help.

The relay refused the connection

After failed, Tatu stops trying. Read the reason in parentheses, fix it, then run /remote stop and /remote start.

The computer did not answer the encrypted channel

A phone or terminal says the computer did not answer, or that it may run an older Tatu. The two sides need the same version: update Tatu on the computer (tatu update) and the app, and check that TATU_REMOTE_E2E is not 0 there, since that turns the encrypted channel off.

A session shows `…` instead of its title

The list of sessions is encrypted, and a device opens it with a key your computer gives it. A new device, or one that was away while another device was revoked, shows … for a moment and then the titles. If they stay as …, open any session of that computer once, or make sure tatu daemon runs there: either one hands the key over. A title that never comes back means the device is not trusted by that computer (next entry), or that the computer runs a Tatu older than this one.

The computer does not trust this device

/remote devices marks a device not trusted by this computer, and a device says the computer does not trust it. Your computer lets in only devices it wrote down itself, whatever the relay says. This happens to devices paired before the encrypted channel, and to a device whose invitation was used up, expired or closed before it finished. Pair it again with /remote pair.

An invitation made by an older Tatu

An invitation that has no key is refused with made by an older tatu. Update Tatu on that computer and make a new invitation.

A version mismatch

A reason that says unsupported_protocol, or an app that says This session needs a newer version of the app, means the two sides speak different versions. Update Tatu with tatu update and update the app. See Install and update.

Tatu starts slowly or offline

At start, Tatu asks for the model catalog and, in an interactive session, for the newest version. Both run in the background and give up quietly when there is no network; the failure goes to the log. You cannot talk to a model without a network, but you can open Tatu, read old sessions and change settings.