Troubleshooting

Start with the setup page's Status section (Check that it runs), or, while deputy-mcp runs:

curl http://127.0.0.1:7331/health

Deputy's messages are written for your agent as well as for you, so most of them say what to do next.

Connecting

Deputy can't reach the browser

Deputy can't reach the browser: the Deputy extension isn't connected.

deputy-mcp is running, but the extension hasn't connected to it. Make sure Chrome is open with the Deputy extension installed and enabled. It connects by itself within a few seconds of deputy-mcp starting.

Deputy program: not running

The setup page or popup can't find deputy-mcp. It starts when your agent starts: check that you've added Deputy to your client, that your client is running, and that node --version shows 20 or later.

Port 7331 is taken by something that is not Deputy

Another program holds 127.0.0.1:7331. The extension always connects on 7331, so stop that program. deputy-mcp tries the port again every 3 seconds and takes it once it's free.

The Deputy hub went away. Try again in a moment.

The client that owned the connection exited while another agent was using it. Another deputy-mcp takes over within moments; retry the call. See One browser, many agents.

Pro and your key

Each of these comes with what to do, in your agent's answer and on the setup page.

Message	What to do
Deputy needs a Deputy Pro license key	Buy Pro at razin.ai/deputy, then paste the key on the setup page (right-click the Deputy icon, then Options)
The license key on Deputy's setup page is not a valid Deputy Pro key	Check the key you pasted, then Save again
Deputy Pro has ended for this license key	Renew at razin.ai/deputy. The key stays the same
Deputy could not reach its license service to check the key	Check this computer's internet connection. A key that was active keeps working for up to three days without the service

Pages

The tab was open before Deputy was installed or updated. Reload it and Deputy will read it.

"Not a website"

Browser pages (chrome://, edge://) and extension stores are closed to extensions. Open a website instead.

No tools on this page

Tools appear when a page has a form or input fields. Your agent can still read, click and scroll it. Some controls only appear after an interaction: if a site's search lives in a pop-up, Deputy offers the button that opens it, not the field.

The browser did not answer within 30s

The page didn't respond to Deputy in time. If the tab closed during the call, the message says so instead.

Typing doesn't register in an editor

Deputy's clicks and keystrokes are synthetic events, because it doesn't use chrome.debugger. Heavy editors such as Google Docs may ignore them.

A PDF reads as empty

Deputy reads PDFs from their text layer. A scanned PDF has none.

Tools

A tool is missing from your agent's list

It may be switched off under What your agent may do on the setup page. Turn it back on and your agent sees it again at once.

browser_eval asks for "Allow User Scripts"

Open chrome://extensions (edge://extensions in Edge), click Details on Deputy, and turn on Allow User Scripts.

browser_look won't run

Without a Pro key, it says it's part of Deputy Pro. Your agent can use browser_screenshot, or browser_ask and browser_read for text.
Without your permission, it asks you to switch on Allow Deputy Pro to send a screenshot on the setup page.
"Deputy Pro is briefly unavailable (nothing was charged)" means the service or its model couldn't answer. Nothing counts against your plan; try again later, or use browser_screenshot meanwhile.

Too many links

Long pages return 25 links at a time, with the total. Your agent narrows them with actionQuery, or pages with actionOffset. See Long pages.

On this page