Starting the browser
| Message | What to do |
|---|---|
no Chromium found; set OKYRA_CHROME to a Chromium based browser binary | Install Chrome, Chromium, Brave or Edge, or point OKYRA_CHROME at one. The paths okyra checks are on the install page. |
the browser could not start its sandbox, which is usual in containers and as root; set OKYRA_NO_SANDBOX=1 if the container is your isolation boundary | In a container, export OKYRA_NO_SANDBOX=1, then okyra stop so the next call starts the browser again. See Linux containers. |
browser exited before printing its DevTools address; it said: ... | The browser crashed on start. The quoted line is its own last words: often a missing system library on a slim Linux image. Install the distribution's chromium package, which pulls them in. |
timed out after 60s | The browser did not start in 60 seconds. Check the machine is not out of memory, and that OKYRA_CHROME points at the browser binary itself, not an app folder. |
failed to start the browser: ... | The binary could not run at all: wrong path or no execute permission. |
The daemon
| Message | What to do |
|---|---|
daemon did not start, see <path>.log | Read the log it names. If it says path must be shorter than SUN_LEN, the socket path is too long for a Unix socket: set OKYRA_SOCKET to a short path such as /tmp/okyra.sock. |
a okyra daemon is already running on <socket> | From okyra daemon only. One daemon serves every call already; use it, or okyra stop first. |
connection to the browser closed | The browser exited or was closed under the daemon. Run okyra stop, then try again. |
okyra daemon: ... | Over MCP: the server could not reach the daemon and could not start one. The rest of the message says why. |
Changed OKYRA_CHROME, OKYRA_HEADFUL, OKYRA_NO_SANDBOX or OKYRA_CONNECT and nothing happened? The running daemon keeps its browser. Run okyra stop.
Attaching to your browser
| Message | What to do |
|---|---|
<folder>/DevToolsActivePort is missing or empty; turn on remote debugging in the browser at chrome://inspect/#remote-debugging (brave://inspect in Brave) | Remote debugging is off, or OKYRA_CONNECT names the wrong browser or data folder. Turn it on and retry. |
the browser did not accept the connection within 120s; click Allow on its remote debugging prompt, then retry | The browser asked whether to allow the connection and nobody answered. Click Allow, then run the command again. |
Targets and actions
| Message | What to do |
|---|---|
no element matches <target> | Nothing matched in 5 seconds, or the match has no size. Take a snapshot (okyra snapshot -i) and use a ref or the role and name it shows. In a plan, the failure already includes that snapshot. |
@e7 is no longer on the page; take a new snapshot | The page changed since the snapshot. Take a new one. Refs are never reused, so an old ref cannot hit the wrong element. |
<target> has no option X; options: Thin, Deep pan | select lists the options it found. Use one of them, by value or visible text. |
no element matches a file input at <target> | The target is not a file input, a label for one, or a box holding one. Point upload at the input, its label or its container. |
io: <path>: No such file or directory (os error 2) | An upload file or screenshot path does not exist. Plans and MCP need absolute paths. |
unknown key "F13" | press takes the named keys on the CLI page or one character. |
script error: ReferenceError: nope is not defined | The JavaScript in eval threw. The message is the browser's. |
navigation failed: <url>: net::ERR_NAME_NOT_RESOLVED | The browser could not load the URL. The net:: code is Chromium's own. |
timed out after 30s waiting for page load | The load event never fired. The page may still be usable: try okyra snapshot. |
timed out after 10s waiting for the page to settle | From wait only. The page never went quiet; raise --timeout-ms or read the page anyway. See settle. |
no page named p3 | close names a page that is not open. okyra pages lists them. |
Plans
| Message | What to do |
|---|---|
bad plan: unknown variant ... | The plan names an action that does not exist, or is not valid JSON. The rest of the message names the bad value and lists the valid actions. Nothing ran. The list of actions is on the plans page. |
repeat run 1, step 2: no element matches #nowhere | A step inside a repeat failed. Runs count from 1, steps from 0. |
each item 1 ("Ana Silva"), step 2: no element matches ... | A step failed on one item of an each. Records for earlier items are still in the results. Mark steps that may be missing on some items "optional": true. |
each: item 1 ("Ana Silva Open") is not a link to follow; use open "click" | The items are buttons, not links. Add "open": "click", and back if each opens a panel. |
each: give steps to run on each item, such as a named text or extract | An each needs steps. |
each: the list changed after the last item and has 2 items now; ... | Clicking an item re-rendered the list. For links use "open": "page"; for a panel give back. |
repeat only works as a step of a plan | repeat and each run only inside okyra run or okyra_plan. |
Licence
| Message | What to do |
|---|---|
not a valid okyra licence key: not in payload.signature form | From okyra license install. The file is not the key text; copy the whole key from the email. |
licence: invalid (...), counts as no key | From okyra license status. okyra keeps working. Check OKYRA_LICENSE and the saved key file named under key from. |
A licence problem never stops a run. See licence keys.