Troubleshooting and FAQ

This page collects the problems people run into most often, with the messages Botream shows and what to do about them. Start with Where to find the logs when the cause is not obvious.

#Agents

#The agent is offline or does not connect

The tray icon's tooltip and the agent window (tray icon → Open dashboard) show the connection state and the reason. The Logs tab (tray icon → View logs) shows every connection attempt.

After a refusal like the last four, the agent tries again only once a minute, so fix the cause and click Reconnect in the tray menu instead of waiting. Network problems are retried automatically, with growing pauses of up to a minute.

Tip: On an installed agent, the settings belong to the machine and only an administrator can change them. If the Settings window shows Change as administrator, use it.

#The agent connects but runs nothing ("Waiting for approval")

When Require approval for new agents is on (Administration → Settings, Agents), a new agent waits for an administrator. The tray icon turns amber and shows "Waiting for administrator approval". An administrator opens Administration → Agents, finds the agent marked Waiting for approval and chooses Approve. No task runs on the agent until then.

#"No agent is online" or "Several agents are online"

These messages come from captures, recordings and the AI Task Generator, which need the agent on your own computer:

• No agent is online: start the Botream Agent on your computer (Start menu → Botream Agent) and check that it is connected.
• Several agents are online: choose the one on your computer: pick your agent in the dialog.
• Agent '…' is offline or is not approved: see the sections above.

#The agent does not appear in the tray

Check that the BotreamAgent Windows service is running. It starts the tray app on the signed-in user's desktop. If a user exits the tray app on a workstation, it stays closed until the next sign-in; start it again from the Start menu (Botream Agent). On an unattended robot it is started again automatically.

#Element capture and recording

#Web element capture does not start

Web capture and the browser part of the recorder need the Botream Element Capture extension, connected to the tray app on the same computer. The typical error is "The Botream Chrome extension is not connected to this agent. Install it and keep Chrome open, or open the page with a browser command first".

Check, in this order:

1. The tray app runs on the computer where you capture. The Windows service alone cannot capture.
2. The extension is installed in Chrome or Edge (chrome://extensions or edge://extensions). The agent installer adds it through browser policy, which browsers accept only on domain-joined or otherwise managed machines. On other machines, load it by hand; see Installing the extension.
3. The extension is connected. Its toolbar icon shows a red ! while it cannot reach the agent, and its popup shows the connection state. In the agent's Logs tab you see "Browser extension connected" when it connects.
4. Reload the extension. If the icon stays red, press the extension's reload button on chrome://extensions, or restart the browser.

Also note:

• Browser pages such as chrome:// pages, the Web Store and the PDF viewer cannot be captured.
• Elements inside iframes cannot be captured yet; the iframe itself is selected.
• A capture waits up to 120 seconds for your click. Esc cancels it after you confirm.

#Desktop capture or recording does not start

Desktop capture, screen area marking and the desktop part of the recorder are shown by the tray app. Messages such as "Desktop capture needs the Botream Agent tray app (the Windows service has no desktop)" mean the tray app is not running on that computer. Desktop recording also does not start while a task is running on the agent.

#Desktop automation fails under the Windows service

Windows runs services in a separate session (Session 0) that has no desktop: no windows, no mouse, no keyboard. That is why Botream does not run tasks in the BotreamAgent service. The service only keeps the tray app running on the desktop of the signed-in user, and the tray app runs the tasks, where browser and desktop automation work.

So desktop automation needs a signed-in Windows session:

• Workstations: tasks run while someone is signed in.
• Machines that run scheduled tasks: install the agent as Unattended robot. Windows then signs in automatically at every start and the agent runs all the time. See Installing an agent.
• Remote Desktop: on a robot machine, when you close a Remote Desktop window, the agent moves the session back to the console so the desktop stays usable for robots.

Commands that need a screen fail with a clear message when there is none, for example "messagebox needs the Botream Agent tray app; the Windows service has no desktop to show dialogs on". See Desktop automation.

#A selector broke

Pages and programs change, and an element that was found yesterday may not be found today. Botream has three safety nets, and each leaves a trace in the run's log:

Where to look:

• Selector health (Edit tasks permission) lists every element command that ran recently, worst first, with a status: Healed, Fallback, Drifting (found, but the element changed since it was captured: re-capture it before it breaks) and broken ones. A row opens the editor at that command.
• The failed run's page shows the screen picture and the variables at the moment of the failure; AI failure analysis can explain it.
• An administrator can have a daily selector health report emailed (Daily selector health report under Administration → Settings, Notifications).

Self-healing is set under Administration → Settings, Self-healing (Heal elements that are not found, Minimum similarity, Only suggest for clicks that cannot be undone), and per task in Task details under Self-healing. See Finding elements reliably.

#AI features

See AI features.

#Scheduled runs do not start

1. Is the scheduler running? The scheduler runs inside the Botream Server and needs SQL Server. When it cannot work, the Schedules page shows "The scheduler is not working". Administration → System health shows its state and the last error. It recovers by itself once the database is reachable again.
2. What happened last time? The Last run column of the Schedules page shows the outcome of the last trigger; hover over it for the message:
   • Skipped: there was no free agent, the agent was offline, or "The previous run is still going". The schedule tries again at its next time.
   • Failed: for example "The task has never been saved" (the task has no public version: push it first, see Versions) or "The task has been deleted".
3. Is the target agent able to run it? The agent (or a member of the agent group) must be online, approved and not busy. For desktop work it needs a signed-in session: install machines that run schedules as Unattended robot.
4. Was the server stopped at the time? A run is missed when the server was not running at the scheduled time. Under If a run is missed a schedule either uses Skip it (the default) or Run once when back (within 24 h).

See Schedules.

#Signing in

#A user forgot their password

An administrator opens Administration → Users, edits the user and enters a New password. Changing it signs the user out everywhere. Botream does not send password reset emails.

#Sign-in is refused after many attempts

Sign-in attempts are rate limited (by default 10 per minute). Wait a minute and try again. For scripts, see REST API.

#Where to find the logs

Warning: C:\ProgramData\Botream\Server\server.json holds the server's secret keys, including the key that encrypts vault passwords. Never send it with a support request, and keep a backup of it together with the database. See Upgrade and backup.