Troubleshooting

Start with tde doctor

tde doctor
tde doctor --json

It prints what TDE can see about your environment: OS, kernel, shell, TERM, locale and a derived UTF-8 flag, whether the working directory is a git repo and on which branch, which language runtimes are on PATH, and how long the probe took. --json gives the same thing minified onto one line, which is the form meant to be pasted in front of an agent prompt.

Symptom index

TDE refuses to start

Before drawing anything, TDE runs a preflight over seven features and prints a line for each. Only two are fatal:

TDE cannot start on this system — missing required dependencies:

[ok ] interactive terminal
[ERR] PTY support (/dev/ptmx) — kernel devpts/ptmx is required to host app windows
[off] PipeWire (wpctl) — install wireplumber/pipewire (provides `wpctl`)

[ok ] is present, [ERR] is a missing critical dependency, [off] is a missing optional one.

[ERR] interactive terminal means stdout is not a TTY. You get this by piping TDE's output, running it from a CI job, or ssh host tde without a PTY. The hint says it: run TDE inside a terminal, or use ssh -t.

[ERR] PTY support (/dev/ptmx) means the kernel has no devpts. In practice this is a minimal container started without it. TDE hosts every app window on a pseudo-terminal, so there is no fallback.

The other five — NetworkManager, BlueZ, PipeWire, backlight, D-Bus session bus — are optional. They print [off], TDE starts, and the matching rows in Quick Settings are rendered inert rather than hidden, so you can see why the volume control does nothing. The D-Bus probes are capped at 400 ms so a slow VM cannot stall your login.

The Runtime is unavailable

TDE Runtime unavailable: <message>

This is printed to stderr and the desktop still starts. It means the durable Runtime that owns tasks, jobs and bots could not be reached or started. The messages that matter:

Check it directly with tde runtime status. A missing runtime affects My Loop, bots and the semantic CLI; the desktop, apps and Web Share do not depend on it. See Runtime.

Two related errors come from the desktop's own socket rather than the Runtime's:

• TDE is not running (no control socket at …); start TDE first — you ran tde agent … with no desktop up.
• control socket at … exists but is not responding; only the desktop owner may replace it — a stale socket owned by another user, or a hung desktop.

And one restriction surprises people:

My Loop has one canonical runtime; task, catalog, share and chat commands
must use profile 'default'

Alternate --profile values exist for Runtime administration only.

The mouse does not work

TDE is mouse-first and drives everything with SGR mouse reporting (mode 1006). If your terminal does not emit it, clicks do nothing while the keyboard still works.

The one case documented in TDE's own deployment notes: the bare Linux virtual console does not emit SGR mouse at all. Console mouse needs the gpm daemon, and TDE does not consume gpm's protocol yet — so on a raw TTY, keyboard only. A kiosk session or an SSH connection from a real terminal emulator is the mouse-capable path.

Otherwise, check that your terminal emulator has mouse reporting enabled and that nothing between you and TDE is intercepting it. If you run TDE inside another multiplexer, that multiplexer has to be configured to pass mouse events through; TDE has no special handling for it either way.

Alt shortcuts are swallowed

TDE's window-manager shortcuts are Alt plus a letter — Alt+W close, Alt+M minimize, Alt+Tab cycle, Alt+Enter new window, Alt+H/J/K/L to pan. Plenty of environments eat Alt before it arrives: some SSH clients, some kiosk setups, most mobile keyboards, and terminals that map Alt to "send Escape".

That is what esc_leader is for, and it is on by default. Press Esc, then the letter, and TDE treats it as Alt plus that letter.

[wm]
esc_leader = true             # default
esc_leader_timeout_ms = 220   # default; 80–1000

If no key arrives inside the window, the real Esc byte is forwarded to the focused app, so nothing is lost. Both settings are also in Control Center → Shortcuts, labelled Kiosk/remote terminals, and changing them there is persisted.

If shortcuts fire when you did not intend them, the timeout is too long — lower it. If Esc-then-letter does nothing, the timeout is too short.

Images are blocky

Your host terminal decides whether TDE can draw real pixels. If it supports none of kitty graphics, iTerm2 inline images or sixel, images and PDF pages are rendered as coloured Unicode block mosaics at cell resolution. Nothing errors — it just looks like a mosaic.

If you see tofu, boxes or garbage instead of a picture, your font lacks the block glyphs TDE picked. Force a coarser mode:

TDE_BLOCKS=sextant tde     # 2×3 blocks, Unicode 13
TDE_BLOCKS=half tde        # the widest-supported fallback

Accepted values are half, quadrant, sextant and octant. TDE defaults to octants on kitty, ghostty, foot and rio, and sextants everywhere else.

Full detection order, the four tiers and which apps use them are on Terminal graphics.

Web Share is unreachable

Work through it in this order.

1. Which reach is it on? Loopback binds 127.0.0.1 and is unreachable from anywhere else by design. LAN, Tailscale and Public all bind every interface — if those fail, it is your firewall or your routing, not TDE.

2. Is a funnel involved? Public reach needs Tailscale Funnel on the host, and it never hard-fails: when the funnel cannot start, the URL silently falls back to the private tailnet address. A link that looks fine may simply not be openable from outside your tailnet. Check the Web Share panel, which reports the specific reason:

3. Is the URL intact? The token lives in the fragment after #. A URL pasted through something that strips fragments produces share URL has no fragment, and a token that no longer matches closes the WebSocket with HANDSHAKE_REJECTED — which is also what you get after rotating the link.

4. Is it the right command? tde share start accepts local, tailnet and public only, and its local means loopback. There is no CLI value for LAN; use Control Center. Anything else gives web-share start: invalid reach …; expected local, tailnet, or public. See Web Share and tde share.

An agent CLI is missing or logged out

TDE detects agent authentication by looking at credential files, never by spawning the CLI. Control Center → LLM shows one of four states:

The login commands TDE runs for you are claude auth login, codex login --device-auth, cursor login and opencode auth login. Codex uses device auth deliberately so TDE can show a QR code and you can complete it on another machine.

When a run fails before it starts, the messages are specific:

• native session target is not ready: … — missing CLI, missing login, or a missing license for a managed model.
• Agent 'X' was not found — the agent name does not match a configured agent.
• could not sync TDE Control MCP into <agent> config at <path> — TDE could not write the agent's MCP configuration, so it refused to run rather than run without its tools. See MCP.

The theme resets on restart

This is a known bug, not a configuration subtlety. Picking a theme in Control Center or flipping with Alt+Shift+E changes the running desktop, but TDE never writes a [theme] table back to config.toml — it is not among the sections the desktop persists. The next start reads whatever the file says.

Pin it by hand:

[theme]
name = "gruvbox"

See Themes for the full palette list and the caveats.

The terminal is wrecked after a crash

If TDE dies without unwinding, your shell can be left with mouse reporting, focus reporting and bracketed paste still on — which shows up as escape gibberish whenever you move the mouse or paste. TDE writes an explicit reset on exit that covers every mode it enables, including ones the terminal library does not track, so this should be rare. When it happens:

reset

Other messages worth recognizing

Filing a report

Include tde doctor --json, the exact message, and — for Runtime or job issues — the relevant log:

Do not open a public issue for a security problem — see Security.

Related

• Installation
• Configuration
• Runtime
• Terminal graphics
• Security