DocsTroubleshooting

Troubleshooting

When something goes wrong, your agent usually says so with Tilda’s own message. Find the message below. Placeholders such as <reason> stand for the part that changes.

Your agent can’t reach Tilda#

Tilda isn’t running, or isn’t installed#

Cannot reach the Tilda daemon at ~/.tilda/daemon.sock: <reason>. Install and open the Tilda app (https://tilda.net/download); it serves this socket.

The plugin opens Tilda by itself when nothing serves the socket. It says this when it couldn’t: the reason is the Tilda app (net.tilda.app) is not installed, or the Tilda app did not open it within a number of milliseconds. Install Tilda or open it, then ask your agent to try again.

Tilda refused the agent#

The Tilda daemon at ~/.tilda/daemon.sock did not admit this agent: refused pid <pid> (<executable>) on the agent socket: neither it nor any ancestor is this app or a trusted agent; lineage: <processes>.

Neither the process nor anything that started it is signed by the maker of a supported agent. The lineage lists each process Tilda checked. Run the agent as its maker ships it; a build of your own is refused. What Tilda admits lists who is.

The app and the plugin are from different releases#

The Tilda app at ~/.tilda/daemon.sock speaks daemon protocol <n>, but this Codemode needs <m>. Update the Tilda app and Codemode to matching releases (https://tilda.net/download).

Update both: download the latest Tilda, and update the plugin in your agent.

Something else answered on Tilda’s socket#

The Tilda daemon at ~/.tilda/daemon.sock accepted the connection but did not identify itself within 5000ms.

The socket accepted the connection, but nothing on it greeted the plugin as Tilda does. Quit Tilda and open it again.

Tilda closed the connection#

The Tilda daemon closed the connection.

Tilda quit or restarted while the agent was connected. Open Tilda, then ask your agent to try again.

A browser or terminal fails#

More than one browser is connected#

More than one browser is connected: <browsers>. getDefault() only works when exactly one is connected. Use agent.browsers.list() then agent.browsers.get(id) to pick one.

Tell your agent which browser to use, or close the others. Each running browser with the extension connected counts.

tmux is missing#

agent.terminals needs tmux 3.5 or later and could not run "tmux" (<reason>). Install it with `brew install tmux` or `apt install tmux`.

Install tmux with brew install tmux, then ask your agent to try again.

tmux is too old#

agent.terminals needs tmux 3.5 or later; "tmux" is tmux <version>. Upgrade it.

Upgrade it with brew upgrade tmux.

Your browser isn’t listed#

If Tilda’s window shows No browser connected, choose Register with browsers, then make sure the Tilda extension is loaded and turned on; Install has the steps. If a row says macOS blocked a browser, give Tilda Full Disk Access and register again.

A Mac app won’t respond to an agent#

Check that Accessibility and Screen Recording show Allowed under Computer Use in Tilda’s window. When a permission is missing, the agent’s error names the System Settings pane to open.

The rest of this page is the troubleshooting guide agents read for browser errors.

The troubleshooting document#

Agents read this as agent.documentation.get("troubleshooting"). It’s written to them, and shown as they read it.

  • "In use by another agent": work in a page of your own, or wait.

  • "No browser extension connected": ask the user to open the Tilda app, register it with their browsers, and load or enable the Tilda extension; its popup shows the connection and a Connect button. Do not use another automation route.

  • "DevTools is open on this page": ask the user to close DevTools for that page, or use a different page.

  • "This page cannot be controlled": browser internal pages such as chrome:// and the Web Store cannot be controlled.

  • "This page is no longer attached": get a new page from context.newPage(). Keep the browser and context bindings.

  • SessionInterruptedError: another extension's frame briefly detached the debugger, and Tilda restored it. The interrupted action may already have taken effect; check the page before retrying. If foreign frames keep being inserted and cannot be neutralised, the page closes with Chrome's original detach reason instead of waiting indefinitely.

  • "Strict mode: matched N elements": use first(), nth(index), or a filter.

  • "Another element intercepts the click": remove the overlay or scroll it away.

  • "No <option> matches": read the available values and labels.

  • "Unknown key": use one character or a named key such as Enter or Tab.

  • Cross-origin iframe: open the frame URL in its own page.

  • A dialog blocks input: register a dialog listener or wait before the action.