Browser troubleshooting

The Tejus in-app browser is a shared Chromium surface scoped to the owning thread. Browser failures are safest to handle with an observe–act–observe loop: inspect the current page, perform one bounded action, then inspect the resulting state.

Tabs and browser tool access belong to the thread. Cookies and signed-in sessions are shared across all Tejus browser tabs and agent workflows; see Browser logins & sessions.

Browser is unavailable

Start with browser_status when the provider has browser tools.

Check:

• The thread owns or can acquire a browser tab
• The Tejus window is open (the browser runs inside the desktop app)
• The tab was not closed or crashed
• The operation targets the current thread’s tabs

Opening another chat does not necessarily destroy the thread’s browser. Do not create repeated tabs simply because the browser surface is hidden; press Ctrl+Shift+B to show it again.

If the panel shows Browser is unavailable., close and reopen the browser panel. If it persists, restart Tejus and collect diagnostics.

No tab is assigned

Use browser_tabs to inspect tabs in the thread’s scope, then browser_open to create or reuse one.

• Omit tabId to use the thread’s assigned tab
• Use only tab IDs returned for the same thread; another thread’s tab is rejected
• Use reuse:false only when a genuinely new tab is required
• Use show:false when background work is appropriate and the page does not require human interaction

Do not guess a tab ID from another thread.

Page is clipped or leaves empty space

An agent can use browser_resize to test a fixed page size. Resizing or reopening the browser panel, or switching between its floating and docked views, returns the page to the panel’s own size without reloading it. Moving a panel without changing its size keeps the requested viewport.

The floating browser always lays the page out at 1280×800 and scales it to fit the card, so a small floating card shows a scaled-down page rather than a narrow layout.

Element reference is stale

Element references from snapshot() are valid only inside the browser_run call that produced them. A reference from an earlier call, or from before navigation, scrolling, resizing, or a page update, can point at the wrong element or none.

When a stale-reference error occurs:

1. Run a new browser_run that observes the current page.
2. Find the element again, preferably by role, label, or text.
3. Act on the new target in the same call.
4. Retry only the intended action.

Action timed out

A timeout does not prove that the action failed.

For clicks, typing, navigation, form submission, uploads, or scripts:

1. Do not immediately repeat the action.
2. Observe the page again.
3. Check the URL, visible text, form value, and page state.
4. Use browser_logs when console or network evidence matters.
5. Retry only when the observed state proves the effect did not happen.

Repeated blind retries can submit forms twice, create duplicate records, or overwrite text. browser_run scripts are limited to 30 seconds; split long flows into smaller steps.

The agent stopped because you used the browser

If you click, type, or scroll in the browser while the agent is acting, your input takes over and the agent’s current browser action is interrupted. That is expected. Finish what you were doing, then ask the agent to observe the page and continue.

Typing produced no visible text

Check:

• The target is editable and enabled
• The element was found on the current page
• The field was replaced when you expected append behavior, or appended when you expected replacement
• A re-render did not replace the input during the action
• The page did not reject the value after an input or change event

Observe again and inspect the field value. For long text, enter it in bounded chunks and verify after each committed step rather than assuming one large action succeeded.

Click opened a sign-in or permission popup

Stop browser automation when the result reports that human action is required.

1. Reveal the owning thread’s browser surface.
2. Complete sign-in or consent yourself in the visible popup.
3. Do not inspect, type, or copy credentials through page scripts.
4. Resume only after the popup or redirect has settled.
5. Observe the page again because its state may have changed.

Popups that try to open a non-web address (a custom URL scheme that would launch another app) are blocked.

Navigation succeeded but the page is not ready

A load event can finish before client-side content is usable. Wait for a specific condition rather than a fixed long sleep. browser_navigate can wait for commit, domcontentloaded (the default), load, or networkidle; inside browser_run, wait for the element or URL you need:

await page.getByText("Dashboard").waitFor();
return await page.url();

After the wait completes, observe the page again.

Browser logs are empty

browser_logs returns bounded console, exception, and network metadata for the exact tab. It never returns headers, request bodies, or response bodies.

Empty results can mean:

• No matching event was captured
• The relevant event occurred before capture
• The failure is outside the page
• The evidence was truncated or not retained
• The wrong tab was inspected

Do not treat an empty log result as proof that no browser or network failure occurred.

Upload was rejected

Browser uploads accept regular files inside the thread’s workspace.

Check:

• Each path is workspace-relative (one to 32 files)
• The target is an enabled input[type=file]
• The path does not traverse outside the workspace
• The file is not a directory
• A symlink does not escape the workspace
• The upload matches explicit user intent

Never upload credentials, private keys, environment files, or proprietary artifacts without explicit authorization.

Download needs approval

When an agent action starts a file download, nothing is written until you approve it. The agent should ask rather than retry.

Keyboard command was rejected

Agent keystrokes are limited to page-level editing, including copy and paste. App and browser shortcuts—such as Ctrl+T, Ctrl+W, Ctrl+N, Ctrl+L, Ctrl+R, Ctrl+P, DevTools chords, Alt+F4, Alt+←/Alt+→, and Ctrl+Alt+Delete—are blocked.

Use visible page controls, or the dedicated browser_back, browser_forward, and browser_reload tools, instead of attempting to bypass the policy with shortcuts.

Screenshot differs from structured output

A screenshot answers pixel-level questions. A structured read answers structure, visible text, roles, state, and actionable targets.

Use:

• browser_run reads and snapshot() for interaction and accessibility structure
• browser_screenshot for layout, clipping, colors, canvas, or image evidence
• Both when visual appearance and interactive semantics disagree

Do not interact from screenshot coordinates when an element can be found by role, label, or text.

A page script failed or changed the page

browser_run scripts can change the page, including through page.evaluate.

Before retrying:

1. Inspect the current page.
2. Determine which actions in the script completed.
3. Prefer normal browser actions for the recovery.
4. Avoid using scripts to bypass navigation, network, upload, or download policy.

Browser crashed or disconnected

Record:

• Thread and tab ID
• URL
• Last successful tool call
• Exact error code
• Whether the action may have taken effect
• Whether the tab appears in browser_tabs
• Whether a new tab reproduces the failure

Close a crashed tab only after preserving evidence. browser_close is permanent for that tab and cannot be undone.

Cookie import failed

On Windows, Saved logins → Import browser cookies can read Google Chrome and Microsoft Edge profiles on your PC. If no supported browser is found, the dialog reports that cookie import is unavailable; sign in directly in the Tejus browser instead.

Use the message shown in the dialog to choose the next step:

An acquisition or generic reader failure does not establish that access was denied. Check the selected profile and the reported failure instead of treating every error as a permission problem.

Saved logins are locked or saving is unavailable

Open Saved logins and use Unlock, or Set master password if setup is required. Password saving needs Offer to save passwords turned on (it is off by default) and an unlocked vault. If saving fails, reopen the browser and retry. If master-password verification fails, wait briefly and retry; the interface cannot reset a forgotten master password.

Allow agents to find saved accounts (on by default) lets agents list which saved accounts exist for the site currently open in the tab—metadata only, never the password. It does not let agents fill, generate, or change passwords—those operations are not available to agents.

Browser recovery checklist

• The correct thread and tab scope were confirmed
• The current page was observed before acting
• Element actions used targets found on the current page
• Ambiguous actions were observed before retrying
• Sign-in and credential steps were left to you
• Logs and screenshots were used only when relevant
• Upload paths stayed inside the thread’s workspace
• The final user-visible result was verified

Continue with Browser verification for the normal workflow or Diagnostics when the browser and thread state disagree.