Fix 'Browser Not Found' Error in AI Agent Browser Tools: Install Chrome/Chromium for Playwright in Hermes, Claude Code, and Other Agents
When AI agents attempt to use browser automation tools (browser_navigate, browser_snapshot, browser_click) on a fresh environment, the browser binary may not exist. This produces a 'browser not found' error that blocks all web testing, screenshot capture, and UI interaction. Unlike the Playwright library error (Candidate 1), this is specifically about the agent's browser tool discovering that Chrome/Chromium is entirely absent from the system. ## Agent Decision Tree 1. Check error message for 'browser not found' or 'Chrome not found' → Solution A (install browser) 2. If message mentions Puppeteer cache, Playwright cache, or system paths → the tool searched but couldn't find the binary anywhere → Solution A 3. If already installed but not found → Solution B (check PATH and cache locations) 4. If running in Docker/sandbox → Solution C (Docker-specific browser setup) 5. After fix: browser_navigate('about:blank') must succeed
Symptoms
- browser_navigate fails with error mentioning 'browser not found' or 'Chrome not found'
- Agent browser tools all return errors without any page loading
- browser_vision returns 'no browser session active'
Error signatures
Browser not found. Chrome not found in agent-browser cache, system paths, Puppeteer cache, or Playwright cache
Error: No browser executable found. Please install Chrome or Chromium
Could not find Chromium. Tried: /usr/bin/google-chrome, /usr/bin/chromium-browser, /usr/bin/chromium
browserType.launch: Executable doesn't exist
Possible causes
- Fresh system without any Chrome/Chromium installation — most cloud VMs and containers ship without a browser
- Agent browser tools expect Playwright-managed Chromium but Playwright was never run with `npx playwright install`
- System Chrome exists but at a non-standard path not in the agent's search list
- Browser was installed via snap (Ubuntu) which puts it in /snap/bin/ — not in Playwright's default search paths
Solutions
Solution C: Docker/sandbox browser setup with --no-sandbox
In Docker containers, Chromium requires --no-sandbox flag because the container's security profile doesn't support Chromium's sandboxing. This is not a missing-browser problem but surfaces similarly because the browser fails to launch.
- Install Chromium per Solution A or B
- Set Puppeteer/Playwright launch args to include --no-sandbox
- Also add --disable-dev-shm-usage to avoid /dev/shm size limits
- For Playwright: configure launchOptions in browser context
Commands
export PLAYWRIGHT_LAUNCH_ARGS='--no-sandbox --disable-dev-shm-usage'
npx playwright install --with-deps chromium
Config examples
// Playwright launch config for Docker
const browser = await chromium.launch({
args: ['--no-sandbox', '--disable-dev-shm-usage']
});Risks
- --no-sandbox disables Chromium's security sandbox — only use in trusted container environments
- --disable-dev-shm-usage uses /tmp instead of /dev/shm for shared memory — slightly slower
Verification
- Step 1: Run `docker run -it --rm node:20 npx playwright install chromium 2>&1 | tail -3` → expect: download completes
- Step 2: In container, run `chromium-browser --no-sandbox --headless --disable-gpu --dump-dom about:blank 2>&1; echo exit=$?` → expect: HTML output, exit 0
Solution B: Install Chromium via system package manager
If npx is not available or Playwright download is blocked, install Chromium via apt (Ubuntu/Debian) or brew (macOS). This installs to system paths that agent browser tools also check.
- Ubuntu: apt-get install -y chromium-browser
- macOS: brew install chromium
- Verify the binary: which chromium-browser or which chromium
- If installed but agent still can't find it → create symlink to expected path
Commands
apt-get update && apt-get install -y chromium-browser
which chromium-browser || which chromium || which google-chrome
chromium-browser --version # confirm it works
Risks
- Chromium from apt may be outdated (Ubuntu LTS often ships older versions)
- snap-based Chromium on Ubuntu has sandbox restrictions that cause 'user namespaces' errors in Docker
Verification
- Step 1: Run `which chromium-browser 2>&1; echo exit=$?` → expect: '/usr/bin/chromium-browser', exit 0
- Step 2: Run `chromium-browser --version 2>&1; echo exit=$?` → expect: 'Chromium X.X.X' version string, exit 0
- Step 3: Retry agent browser action → expect: browser launches successfully
Solution A: Install Chromium via Playwright (preferred for agents)
For agent environments, Playwright-managed Chromium is the cleanest option. It installs to a known cache location that most agent browser tools check first. No system package manager needed.
- Run npx playwright install chromium (or npx playwright install --with-deps chromium for system libraries)
- Verify the binary exists at ~/.cache/ms-playwright/
- Retry the browser action
Commands
npx playwright install chromium
ls ~/.cache/ms-playwright/chromium_headless_shell-*/chrome-headless-shell-linux64/chrome-headless-shell
Risks
- Requires Node.js/npm to be installed
- ~300MB download for Chromium + headless shell + ffmpeg
- May also need system libraries (see Candidate 1 for library fix)
Verification
- Step 1: Run `ls ~/.cache/ms-playwright/chromium_headless_shell-*/chrome-headless-shell-linux64/chrome-headless-shell 2>&1; echo exit=$?` → expect: file path printed, exit 0
- Step 2: Run `npx playwright install chromium 2>&1; echo exit=$?` → expect: 'chromium' listed in output, exit 0
- Step 3: Retry browser_navigate('about:blank') → expect: page snapshot returned
Agent JSON
Canonical machine-readable representation of this issue:
{
"issue_id": "4b5ddb40-50e2-4fea-95cf-026926547445",
"slug": "fix-browser-not-found-error-in-ai-agent-browser-tools-install-chrome-chromium-for-playwright-in-hermes-claude-code-and-o-2edtc8",
"verification_status": "unverified",
"canonical_json": "https://codekb.dev/v1/issues/fix-browser-not-found-error-in-ai-agent-browser-tools-install-chrome-chromium-for-playwright-in-hermes-claude-code-and-o-2edtc8"
}