Errors

When cora fails, it prints the error’s code, a hint and a link to its entry on this page:

error[browser.not-installed]: Google Chrome was not found
hint: Install Google Chrome, or run: `npx playwright install chrome`
docs: https://cora.vispero.com/docs/0.10/reference/errors/#browsernot-installed

From 1.0.0 on, codes never change meaning, and a code that cora stops raising stays listed here. Exit codes gives the exit code an error sets.

contract.wrong-format

A file cora was asked to read is not the kind of CORA file it expected, such as a baseline passed where a results file belongs.

Hint: Check that the file is the CORA file you meant to pass.

contract.unsupported-version

The file was written by a newer release of cora, in a format version this release cannot read.

Hint: Update @vispero/cora to the release that wrote this file, or a later one.

contract.invalid

The file has the right format and version but its content is not valid. The message lists each problem with its path inside the file.

Hint: Fix the fields listed above, or write the file again with cora.

contract.unknown-fields

cora was asked to rewrite a file, such as cora.baseline.json in cora baseline update, that holds fields this release does not know, written by a newer cora or by hand. Rewriting it would drop them, so cora refuses and writes nothing; the message lists each field with its path.

Hint: Update @vispero/cora to the release that wrote these fields, then run the command again.

config.invalid

cora.config.ts or cora.config.json does not match the config schema; the message lists each problem with the key it concerns and what the key takes, such as page.timeout: Expected a number, or Unknown key `pageTimeout` for a key the schema does not have. A rules entry for a rule cora does not have is rejected too, as is a cora.config.ts without a default export.

Hint: Fix the problems listed above; an unknown key is rejected because it is usually a typo.

config.ambiguous

The project root holds both cora.config.ts and cora.config.json.

Hint: Keep one of cora.config.ts and cora.config.json.

config.load-failed

Loading cora.config.ts threw an error, such as a syntax error or a failing import, or reading the config it exports did, such as a getter that throws. The message gives the error, which may come from the config file or from a module it imports.

Hint: Fix the error the config file throws while it loads.

config.invalid-environment

An environment variable cora reads, such as CORA_LOG_LEVEL or CORA_BASE_URL, holds a value cora does not accept. The message names the variable and what cora accepts, and the value unless it could hold a secret, as a proxy’s URL or a variable named like a secret can.

Hint: Fix or unset the environment variable named above.

config.development-only

A variable or a flag set a setting that only a run of CORA from its source takes, one CORA’s own developers use, so a release refuses it. The message names the variable or the flag and the setting. A release ignores such a setting in your user config, with a warning, rather than failing.

Hint: Unset the variable or the flag named above: only a run of CORA from its source takes it.

cli.invalid-argument

A command, option or option value is not one cora accepts, such as --shard 3/2, or no command was named. The hint names the help that lists what cora accepts there, cora --help for the commands or the command’s own, such as cora scan --help, for its options and arguments, after the command or the option cora suggests for a typo.

Hint: Run cora --help for the commands and their options.

cli.confirmation-required

A command that asks before it changes anything, as cora init asks before it writes, could not ask: stdin or stderr is not a terminal, stderr’s log format is json, or -q left out what the question is about. A person may be running the command, so cora takes nothing as confirmed, and changes nothing. In CI and under a coding agent, where nobody answers a question, the command goes on without asking.

Hint: Run the command again with --yes to go on without asking, or at a terminal without -q or --log-format json to answer its question.

cli.state-unwritable

cora scan could not create or write its state directory, which the message names: .cora/ in the project root, or outside a project in the folder you run cora in, unless stateDirectory moves it. A scan writes its run there, and in CI its report directory, so it checks the directory before it scans rather than failing once the scan is done. --out and --report write the run and the report where they name instead, and a scan that writes neither to the state directory checks nothing.

Hint: Run cora in a folder you can write, or set CORA_STATE_DIRECTORY, or stateDirectory in your user config, to a directory you can write.

file.not-found

A file or directory cora was asked to read does not exist, such as an input of cora report merge or a baseline named with --baseline.

Hint: Check the path; a relative path starts from the working directory.

file.unreadable

cora could not read a file or directory it was asked to read, such as one without read permission, or a directory where a file belongs.

Hint: Check that the path names a file cora may read.

file.write-failed

cora could not write one of the files it writes, such as a run file in the state directory’s runs/ (.cora/runs/ by default), a results file named with --out, a file in the report directory, the baseline, a file cora init writes or a log file in the state directory’s logs/, or could not delete an old log file it prunes.

Hint: Check that the directory is writable and that the disk is not full.

init.file-changed

A file cora init was about to write changed after it read the file and showed its changes, such as in an editor or by another process. cora init checks every file before it writes any, and writes none when one changed; it checks each file again just before its own write, and one that changed by then stops it there. The message names the file, and any files it wrote before it.

Hint: Run cora init again, which plans its changes from the files as they are now.

merge.no-inputs

cora report merge or cora baseline update was given directories that hold no .json file. A directory contributes the *.json files directly in it, not those in its subdirectories; when CI downloads each shard’s results with actions/download-artifact, set merge-multiple: true so they land in one directory.

Hint: Name results files, or the directories that hold them.

merge.conflicting-runs

Two inputs hold a run with the same ID but different content. A run that arrives in several inputs is merged once, so its copies must be identical; one of them was edited, or written by another run that reused the ID.

Hint: Pass each run once, or write the changed file again with cora.

merge.duplicate-shard

Two different runs claim the same shard of one sharded run, which they share when they have the same producer, config, rules, commit and shard total. This happens when the results of two sharded runs of one commit, such as a nightly run and a pull request’s, are merged together.

Hint: Merge one results file for each shard, and remove the extra one.

merge.incomplete-shards

A sharded run is missing at least one shard, such as a CI job that failed before uploading its results file. Every shard from 1 to the total must be merged, or the gate could pass on targets nobody scanned. The shards of one run must also share their config’s hash, so they may differ only in the keys the config reference marks as outside configHash.

Hint: Merge the results of every shard; the message lists the missing ones.

target.invalid

A target’s URL or state is not one cora accepts: the URL is not an http or https URL, or is a path while the config has no baseUrl; or the state is empty, or is named for a page reached by navigation, since only a state reached by interaction has a name. There may also be no targets at all. Paths resolve against baseUrl or --base-url, and targets come from the command line or the config’s targets.

Hint: Name http or https targets, and set baseUrl for targets given as paths.

scan.invalid-scope

A scan was limited to part of a page by CSS selectors, and one of them cannot apply there: a selector of cora-mcp’s include or exclude, or of the config’s page.exclude, is not valid CSS; an included selector matched nothing on the page; an included selector matched an element on or inside one that page.exclude leaves out, since a scan’s own scope only narrows what the config scans; or an excluded selector matched the page’s root element, such as html, which would leave out the whole page. To scan nothing on a route, turn its rules off in the route’s rules.overrides, such as with axe/* set to off, or keep a crawl off it with crawl.exclude.

Hint: Fix the selector named above, or leave it out of the scan’s scope or the config’s page.exclude; to scan nothing on a route, turn its rules off in its rules.overrides, or keep a crawl off it with crawl.exclude.

scan.unsupported-page

The page to scan is not an http or https page, such as a blank tab or a file: page, or it reported a viewport of no size, or a script cora runs in the page answered in a shape cora does not expect, such as when the page replaced a built-in the script calls. Run files record pages by their http or https URL, so cora scans no other page.

Hint: Serve the page over http, or fulfil an http route with its content.

server.already-running

The URL in the config’s server already answered before cora scan ran the server’s command, so another server is running there, and server.reuseExistingServer is off. cora scan started nothing and scanned nothing. Stop that server, such as one an earlier run left running, or turn server.reuseExistingServer on, in the config or in your user config, to scan the server that answers.

Hint: Stop the server answering at server.url, or turn server.reuseExistingServer on to scan it.

server.exited

The command in the config’s server exited, or could not start, before its URL answered. The message gives its exit code, or the signal that ended it, and the end of its error output, and for a command that could not start, the system’s code for why, such as ENOENT; never the command itself, which may hold a secret. The shell runs the command, so a program that is not on the PATH ends this way too, with the shell’s exit code, 127 on Linux and macOS, and the shell’s error in the output. A server that cannot listen, such as on a port another process holds, ends this way, as does a build that fails before it. cora scan --debug keeps the command’s whole output in the log file.

Hint: Run the config’s server.command yourself, and fix the error it prints.

server.timed-out

The URL in the config’s server did not answer within server.timeout, whose value the message gives, after cora scan ran the server’s command, so cora scan ended the command and every process it started. The message says what the URL last did, such as refuse the connection, with the network error’s code, such as ECONNREFUSED, or answer with status 404, and gives the end of the command’s error output. Where the machine does not trust the certificate the URL presented, the hint says to turn browser.ignoreHTTPSErrors on, or to have the server present a certificate the machine trusts, since the scan’s browser refuses that certificate too. Check that the URL names the address and port the server listens on, or raise server.timeout for a build or a start that takes longer. cora scan --debug keeps the command’s whole output in the log file.

Hint: Check that server.url is where the server answers, or raise server.timeout.

page.navigated

The page kept navigating while cora waited for it to settle before scanning, more often than a chain of 3 redirects would.

Hint: The page kept navigating while cora waited for it; check for a redirect loop or a page that reloads itself.

page.not-ready

The page never became ready by the config’s page.waitFor, so cora did not scan it: the readiness function threw, or the readiness selector is not valid CSS. The message gives the function’s error or the selector.

Hint: Fix the config’s page.waitFor, or the route’s, so it names an element the page shows or resolves once the page is ready.

page.unresponsive

The page stopped answering while cora waited for it to settle before scanning, and did not answer a check that followed within 5 seconds. A JavaScript dialog, such as an alert(), blocks the page until it is answered, and a script that never yields blocks it for good.

Hint: Answer the open dialog, or stop the script that blocks the page, then scan again.

node.unsupported-version

cora or cora-mcp started on a Node.js release older than the oldest one its package supports, which the engines field of its package.json names; the message gives both releases. npm installs a package on an older Node.js with only a warning, so each bin checks the release before it loads anything else, and stops. On a release older than Node.js 16.20, a bin may instead fail with Node.js’s own error before it can check. node --version prints the release that runs; install a later one with the Node.js installer or a version manager, such as nvm, and check that it comes first on the PATH the command runs with, such as an MCP client’s.

Hint: Install the Node.js release the message names, or a later one, then run the command again.

playwright.not-installed

cora launches the browser with the project’s own Playwright, or with the playwright-core it declares as a peer dependency when the project has none, and found neither. npm and pnpm install that peer dependency with cora, but Yarn does not, so with Yarn add playwright-core yourself.

Hint: Install playwright-core, or @playwright/test, in the project.

playwright.unsupported-version

The project’s Playwright is older than 1.51, the oldest release cora supports.

Hint: Update the project’s Playwright to 1.51 or later.

browser.not-installed

cora scans with Google Chrome, the copy installed on the machine, and could not find it. npx playwright install chrome installs it where Playwright looks.

Hint: Install Google Chrome, or run: npx playwright install chrome

browser.launch-failed

Chrome was found but did not start. In a container, Chrome may lack a system library it needs. cora scan raises it when Chrome does not start within 60 seconds, and cora-mcp when Chrome does not start within mcp.callTimeout. For a browser with a window that does not start, such as on a display that refuses the window, cora-mcp and cora scan --headed name the ways to run it headless.

Hint: Run cora with --debug and read the browser’s own error in the log file.

signin.storage-state-not-found

browser.storageState names a file that does not exist. Create it with your Playwright authentication setup, or with npx playwright codegen --save-storage=<file>.

Hint: Check browser.storageState in the config; it is relative to the project root.

signin.setup-failed

The browser.setup function in cora.config.ts threw an error, which the message gives, or did not finish within browser.setupTimeout, 60 seconds by default, or, in cora-mcp’s browser, within mcp.callTimeout, the bound on each cora-mcp call. Either way the browser is closed.

Hint: Fix the error browser.setup throws; it runs once, before the first target.

mcp.no-page

A scan found no page to scan in the agent’s browser: scan_page was called before a page was open, the browser’s tab list failed or marked no tab current, such as after a crash, or browser_close closed the browser while the call ran. Open a page, or close the browser with browser_close and navigate again.

Hint: Open a page with browser_navigate, or scan a URL with scan_url.

mcp.unknown-tab

scan_page was given a tab index that names no open tab. Indexes are the ones browser_tabs lists, starting at 0.

Hint: Call browser_tabs with the action list for the open tabs’ indexes.

mcp.unknown-issue

explain_finding found no readable run that holds the issue in the state directory’s runs/ (.cora/runs/ by default), or the run it was given does not exist or does not hold it. The ID may be mistyped or come from another project, or the run’s file may be unreadable or deleted, since neither cora nor cora-mcp deletes a run. verify_fix, or a fix passed to summarize_fixes, named an issue no readable loop in the state directory’s loop/ holds: a scan starts one for each issue it finds, and removes the loop of an issue no fix has been verified for once a scan of its page as it loads covers its rule there and no longer finds it, such as after an edit to the element’s opening tag gave it a new ID, and summarize_fixes ends the loop of each issue it reports. Scan again for a current issue ID, and pass summarize_fixes the fixes of the issues it has yet to report.

Hint: Pass an issue ID from a scan’s latest result, to explain_finding with the run it came from, and to summarize_fixes only for an issue it has yet to report.

mcp.unknown-rule

get_fix_guidance was given the ID of a rule CORA has no fix guidance for, such as a mistyped ID or a rule only a newer cora knows. Every rule list_rules lists has guidance.

Hint: Pass a rule ID as list_rules or a scan’s result gives it, such as axe/image-alt.

mcp.loop-changed

verify_fix judged a fix against the evidence an issue’s loop held when the call began, and by the time it came to record the attempt, another cora-mcp process sharing the project had started the loop again with a scan’s newer evidence, as a scan does once it finds an issue whose fix was verified. The call records no attempt.

Hint: Call verify_fix again, which judges the fix against the evidence the loop holds now.

mcp.loop-unreadable

verify_fix, or a fix passed to summarize_fixes, named an issue whose loop record in the state directory’s loop/ (.cora/loop/ by default) cora-mcp cannot read, such as one another release of CORA wrote in a format this release does not read, or one that is damaged. A verification whose rescan listed the issue under an ID whose record cannot be read fails so too, recording nothing. A scan starts no loop for an issue while such a record holds its ID, and its log warns of the record as loop record skipped. Deleting the record ends that issue’s loop, and the next scan that finds the issue starts it afresh.

Hint: Delete the loop record the message names, or the state directory’s loop/ to clear every loop, then scan the page again; CORA never deletes a record it cannot read.

mcp.invalid-argument

A cora-mcp tool was called with arguments that do not match its input schema; the message lists each problem with the argument it concerns. browser_tabs fails so for an isolatedContext other than default, an option cora-mcp withholds, since it would open a tab in a browser context CORA’s scans do not read. At startup, the MCP entry’s args held an argument cora-mcp does not take, which the message names, such as an option cora-mcp does not have or a value given to --headless.

Hint: Fix the arguments listed above; the tool’s input schema describes each one.

mcp.browser-timeout

A browser tool or a scan did not finish within the bound on each cora-mcp call, mcp.callTimeout, whose value the message gives: a navigation to a page that never finishes loading does it, as does a script that never yields. cora-mcp stops waiting so the agent’s next call can run, and closes the browser, since the tool or the scan may still be changing the page; the next browser tool opens a new one. A scan_url that runs out of time once its page is loading reports the page as not scanned, timed-out, rather than failing. The agent’s client also stops waiting at its own tool timeout, such as the tool_timeout_sec of a Codex entry, so a longer mcp.callTimeout needs the client’s timeout raised too.

Hint: cora-mcp closed the browser, so the next browser tool opens a new one; check what the page does, or raise mcp.callTimeout, before calling the tool again.

mcp.state-unwritable

A cora-mcp tool that writes CORA’s state could not create or write its state directory, which the message names: .cora/ in the project root, or outside a project in the folder the agent’s client started cora-mcp in, unless stateDirectory moves it. The scans, verify_fix, summarize_fixes and every browser tool write state: a scan’s run, the remediation loop’s records, and the snapshots, screenshots, console logs and downloads of the browser tools. A client starts cora-mcp in the folder it has open, which can be one cora-mcp may not write, such as a system folder. Listing the tools writes nothing, and the tools that only read, list_rules, explain_finding and get_fix_guidance, still work there.

Hint: Open a project folder in your agent, set the cwd of cora-mcp’s entry in your MCP client to a folder it can write, or set CORA_STATE_DIRECTORY in the entry’s environment to a directory it can write.

mcp.release-unavailable

cora mcp could not fetch the @vispero/cora-mcp release at the version of cora it runs, such as when the machine is offline or the registry refuses the request. The message names the release and why: npm reported an error, npx could not start, or the release printed something other than its version. The end of npm’s own error, which can run to many lines, is a debug record: cora --debug mcp prints it and keeps it in the log file.

Hint: Check that npm can reach its registry, then run the command again; cora --debug mcp logs npm’s own error.

installation.bin-missing

cora runs the project’s own @vispero/cora when it is another copy, but that copy’s package.json names no cora bin, so there is nothing to run, as after an interrupted install or an edit to the file. The message names the manifest.

Hint: Reinstall @vispero/cora in the project with its package manager, then run the command again.

installation.spawn-failed

cora or cora-mcp could not start the program it hands over to: npx, which runs the @vispero/cora-mcp release for cora mcp and for a cora-mcp whose version differs from the project’s cora, or Node.js, which runs the project’s own cora. The message names the system’s code for why, such as ENOENT when npx is not on the PATH, and the failure’s log record keeps the system’s own error.

Hint: Check that the program named above is installed and can run, then run the command again.

account.missing

cora found no account credential: CORA_TOKEN is unset, and there is no credentials file, which cora auth login writes in your per-user config directory. An MCP client that passes a server only the variables its entry names, such as Codex, passes cora-mcp a CORA_TOKEN, or an XDG_CONFIG_HOME that moves that directory, only when the entry names it, as CORA’s plugin’s entry does.

Hint: Sign in with cora auth login, or set CORA_TOKEN to a CI token from your CORA account. In an MCP client that passes a server only the variables its entry names, such as Codex, name CORA_TOKEN in the entry, and XDG_CONFIG_HOME where you set it.

account.invalid

The account token, from CORA_TOKEN, the credentials file or the stdin of cora auth login --with-token, is not one the CORA service signed for this release: its signature, issuer, audience or claims do not check out, or the key that signed it is one this release does not hold and the service’s current keys could not be fetched. The message says which. For a key this release does not hold, update @vispero/cora, or run the command again once cora can fetch the service’s keys: connect to the network when cora could not reach the service, or wait a few minutes when the service was unavailable. --with-token also raises it when stdin holds no token, holds more than any account token, or does not end within 60 seconds.

Hint: Sign in again with cora auth login, or check the token in CORA_TOKEN.

account.expired

The account token has expired and was not renewed. A token in CORA_TOKEN, such as a CI token, is never renewed; a signed-in token is renewed while the service accepts its refresh token, and the message says why its renewal did not finish.

Hint: Sign in again with cora auth login, or set CORA_TOKEN to a current CI token.

account.login-failed

cora auth login did not finish: the login was denied on the verification page, the code expired before the login was approved, the service ended the login with another error, which the message names, or the service named a verification page outside its own https origin, which cora refuses.

Hint: Run cora auth login again, and approve the login on the page it shows before the code expires.

service.client-outdated

The CORA service refused a request because the release of cora or cora-mcp that sent it is older than the oldest release the service serves. cora-mcp runs at the version of the project’s @vispero/cora, so updating that updates both; in a project without cora, cora-mcp runs the version its MCP entry names.

Hint: Update @vispero/cora to its latest release, then run the command again.

service.unreachable

cora could not reach the CORA service, or the service did not answer within the request timeout, service.requestTimeout in your user config: the machine may be offline, a firewall may block the connection, or the proxy named by HTTPS_PROXY or HTTP_PROXY may have refused it. The message says what failed, with the network error’s code, such as ECONNREFUSED, or gives the timeout it reached; the log keeps the network’s own error. On a network that reaches the internet only through a proxy, name the proxy in HTTPS_PROXY; on one whose proxy or VPN is slow, raise service.requestTimeout. When the machine does not trust the certificate the connection presented, as on a network whose TLS-inspecting proxy signs its connections with a root the operating system’s store lacks, the message says so and gives the TLS error’s code, such as SELF_SIGNED_CERT_IN_CHAIN, and the hint names the fixes: install the proxy’s root certificate in the operating system’s store, or name a PEM file that holds it in NODE_EXTRA_CA_CERTS (Trusted certificates).

Hint: Check the network connection, and the proxy in HTTPS_PROXY if the network needs one, then run the command again.

service.unavailable

The CORA service answered a request with a 500, 502, 503 or 504 status, or could not finish renewing a signed-in account token: the service, or the gateway in front of it, could not serve the request, such as when the service fails on it, is overloaded or is restarting. The fault is the service’s, not the account credential’s or the network’s, so signing in again does not help. The message gives the status, or says the renewal did not finish, and cora then keeps the refresh token the service answered with.

Hint: The CORA service is having trouble, not your credential; run the command again in a few minutes.

internal.unexpected

cora hit a bug, wrote a crash file with its recent log records, and printed the file’s path. Review the file before sending it, since it may contain URLs, file paths and page content.

Hint: This is a bug in cora; send the crash file to cora@vispero.com.