Troubleshooting

Start with dejo doctor. It checks the browser, the profile, the memory and the downloads folder, and prints the exact fix for anything missing.

dejo doctor

Each line starts with ok, FAIL (Dejo cannot work until it is fixed) or -- (not needed yet). The last line is either Everything Dejo needs is here. or a list of what needs fixing.

"Dejo has no browser to drive yet"

pip install brings the code, not a browser. Chromium is a separate download:

python -m playwright install chromium

Nothing is wrong with your profile.

My agent does not see the Dejo tools

1. Run dejo doctor in a terminal. If the command is not found, the folder pip installs commands into is not on your PATH, and your agent cannot find dejo-mcp either. Add that folder to PATH, or give your agent the full path to dejo-mcp.
2. Check your agent's setup page: Claude Code, Codex, Cursor.
3. Start a new chat. Agents load their MCP servers when a session starts.

"Dejo cannot open a window here: this machine has no screen"

Signing in happens in a window a person looks at and types into, so dejo login cannot work over plain SSH or in a container. Normal runs are headless and are not affected. Two ways out:

• Run dejo login on a computer with a desktop, then copy the folder ~/.dejo/browser-profile across.
• Or forward a display over SSH with ssh -X and run it again.

"Dejo could not open its browser profile"

Two things cause this, and the browser does not say which:

1. Another Dejo run or a sign-in window still has the profile open. Close it first.
2. The profile is in a state no browser will accept. Deleting ~/.dejo/browser-profile fixes it, but signs you out of every site.

To run two agents at once, give each its own profile:

DEJO_PROFILE=~/.dejo/profile-b dejo-mcp

"Nothing loads in Dejo's browser profile"

A page timed out in your saved profile, Dejo tried the same address in a fresh browser, and it loaded there. The website is fine; that profile is stuck. Either:

• switch to a new profile (dejo_profile from your agent, or dejo --profile <name> in a terminal) and sign in there, or
• close every Dejo window and delete the profile folder the message names.

A run says the site changed

That is needs_repair. One step broke and the rest of the route is fine. Your agent is shown the controls on the page now, picks the right one, and calls dejo_repair. Only that step changes.

If more than half the steps break, the site was rebuilt rather than adjusted. The run comes back stale: Dejo drops the route but keeps what it knows about the site (it needs a login, it sends a code to your phone), so learning it again costs less than the first time.

A run asks for a password

A step that types a password stores only that a password goes there, never the password itself. Give it one of two ways:

• an environment variable named after the site and the field, such as DEJO_SECRET_BILLING_ACME_COM_PASSWORD
• or ~/.dejo/secrets.json: { "billing.acme.com": { "password": "..." } }

The message names the exact variable to set. More in Signing in.

I want to start over on one site

dejo forget --site example.com

The route is archived and the next run says the memory is gone. Forgetting does not sign you out: the browser session stays until you delete the profile.

Still stuck?

Open an issue on GitHub with the output of dejo doctor. There is a form for "a site Dejo gets wrong".

FAQ