Skip to content
Vibium Vibium Vibium

Troubleshooting

Quick fixes for the most common issues.

First stop: vibium ready (nightly)

Section titled “First stop: vibium ready (nightly)”
Terminal window
vibium ready

On nightly builds, ready checks the installed browser files and, when AI is configured, the model provider used by run and check. It names what is missing and how to fix it. vibium ready browser and vibium ready ai run each half alone. On the npm release, vibium go https://example.com is the quickest health check.

”command not found: vibium”

Section titled “”command not found: vibium””

The npm global bin directory isn’t on your PATH. Either add it (npm config get prefix will show you where), or skip the global install entirely and use npx:

Terminal window
npx -y vibium go https://example.com

If you plan to use Vibium repeatedly in a session, alias it once:

Terminal window
alias vibium='npx -y vibium'

The browser doesn’t appear

Section titled “The browser doesn’t appear”

By default Vibium runs a visible browser. If you don’t see a window:

  • You may be on a headless host (e.g. a CI runner or a remote server with no display). That’s expected; capture commands like screenshot and text still work.
  • Google Chrome for Testing may still be downloading on first use. Re-run the command after it finishes.

”no element matches” from find

Section titled “”no element matches” from find”

Vibium matches semantically: visible text, label, placeholder, role. If nothing matches:

  • The page may not be ready yet — try vibium wait before finding.
  • The text may differ from what you expect — vibium text will show you the actual rendered content.
  • The element may be inside a closed <details>, a hidden tab, or a shadow root that requires scrolling or expanding first.

A reference like @e3 doesn’t work anymore

Section titled “A reference like @e3 doesn’t work anymore”

References are stable while the page is unchanged, and each find or map output defines the current @eN set. If the page navigated or re-rendered, run vibium map (or vibium diff map) to refresh. Get into the habit of running wait after any action that triggers navigation.

Custom binary path

Section titled “Custom binary path”

The Python and Java clients honor VIBIUM_BIN_PATH if you need to point at a locally built binary:

Terminal window
export VIBIUM_BIN_PATH=/path/to/your/vibium

MCP server won’t start

Section titled “MCP server won’t start”

Run the server directly to see the error message:

Terminal window
vibium mcp

If the bundled browser hasn’t been downloaded yet, run any normal command first (for example vibium go https://example.com) so the download completes, then restart your MCP client.

run or check reports a configuration error

Section titled “run or check reports a configuration error”

Run vibium ready ai in the same shell. It lists missing settings and tests the configured provider with up to two small model requests. If you have not configured a provider yet, vibium setup (or vibium config init for just the file) writes ~/.config/vibium/ai.env. See Model providers.

Recordings are huge

Section titled “Recordings are huge”

vibium record captures screenshots per step, and on Firefox a video track as well. Long sessions produce big zips. If you only need a final snapshot, use vibium screenshot instead of record; for long sessions, record chunk splits the output.

Where to ask for help

Section titled “Where to ask for help”
  • Bugs in the vibium binary, library, or MCP server — file an issue at https://github.com/VibiumDev/vibium/issues.
  • Mistakes, gaps, or unclear writing in these docs — file an issue against this docs repository.

When reporting a runtime bug, please include:

  • Your platform and architecture (uname -a or equivalent).
  • The exact command you ran and the full output.
  • The Vibium version (vibium --version).
  • A record.zip from a vibium record session reproducing the problem, if you can.