What causes "Cannot use caCert with clearCaCert" in vercel-labs/agent-browser?

Pick one intent: to trust a CA, keep caCert and delete clearCaCert; to remove the CA, keep clearCaCert: true and delete caCert (or set it to undefined).

vercel-labs/agent-browser · error · Error

Cannot use caCert with clearCaCert

Error message

Cannot use caCert with clearCaCert

What it means

This error is thrown by configArgs() in the eve extension's browser launcher (packages/@agent-browser/eve/extension/lib/browser.ts:144). configArgs() turns the extension config into agent-browser CLI flags: caCert maps to --ca-cert <path> (trust a custom certificate authority) and clearCaCert maps to --no-ca-cert (remove a previously configured CA). The two flags contradict each other, so the guard throws before any browser process is started.

Source

Thrown at packages/@agent-browser/eve/extension/lib/browser.ts:145

  if ((probe.exitCode ?? 0) === 0) {
    return;
  }
  await withDeadline(
    installAgentBrowser(sandbox, {
      abortSignal,
      installBrowser: config.installBrowser,
      installSpec: config.installSpec,
      installSystemDependencies: config.installSystemDependencies,
    }),
    "Installing agent-browser",
  );
}

function configArgs(): string[] {
  const config = extension.config;
  const args: string[] = [];
  if (config.caCert !== undefined && config.clearCaCert) {
    throw new Error("Cannot use caCert with clearCaCert");
  }
  if (config.allowedDomains !== undefined && config.allowedDomains.length > 0) {
    args.push("--allowed-domains", config.allowedDomains.join(","));
  }
  if (config.caCert !== undefined) {
    args.push("--ca-cert", config.caCert);
  } else if (config.clearCaCert) {
    args.push("--no-ca-cert");
  }
  if (config.contentBoundaries) {
    args.push("--content-boundaries");
  }
  if (config.maxOutputChars !== undefined) {
    args.push("--max-output", String(config.maxOutputChars));
  }
  if (config.proxy !== undefined) {
    args.push("--proxy", config.proxy);
  }

View on GitHub (pinned to f9a6cc3421)

Solutions

Pick one intent: to trust a CA, keep caCert and delete clearCaCert; to remove the CA, keep clearCaCert: true and delete caCert (or set it to undefined).
If the config is merged from multiple sources, set caCert to undefined explicitly in the layer that adds clearCaCert: true; a leftover stale or empty string still counts as set.
To replace an existing certificate, pass the new caCert path alone; the stored cert is overwritten, so clearCaCert is not needed first.
Add a startup validation that rejects the combination with a clear message before the first browser command runs.

Example fix

// before — throws: Cannot use caCert with clearCaCert
const config = { caCert: '/certs/corp-ca.pem', clearCaCert: true };

// after — trust a (new) CA
const config = { caCert: '/certs/corp-ca.pem' };

// after — remove the CA entirely
const config = { clearCaCert: true };

Defensive patterns

Strategy: validation

Validate before calling

// Run before registering the extension or issuing any browser command
function validateEveBrowserConfig(config) {
  if (config.caCert !== undefined && config.clearCaCert) {
    throw new Error('Invalid config: caCert and clearCaCert are mutually exclusive');
  }
}
validateEveBrowserConfig(extension.config);

Type guard

// Cert settings are a tri-state: unset, set, or clear — never two at once
function hasCoherentCertConfig(config) {
  return !(config.caCert !== undefined && config.clearCaCert === true);
}

Try / catch

try {
  await runBrowserCommand();
} catch (err) {
  if (err instanceof Error && err.message === 'Cannot use caCert with clearCaCert') {
    // Decide the intent, drop the other key, retry once
    delete extension.config.clearCaCert; // or: extension.config.caCert = undefined;
    await runBrowserCommand();
  } else {
    throw err;
  }
}

Prevention

Treat caCert and clearCaCert as one tri-state field: undefined means no change, a string sets the cert, clearCaCert removes it. Never populate two states at once.
When configs are merged or persisted, resolve the cert fields to a single final value before handing the config to the extension.
The guard checks caCert !== undefined, not truthiness; an empty string still triggers the error, so delete the key or set it to undefined.
Validate the config once at startup with a schema check or a small validator instead of discovering the conflict at the first browser launch.

When it happens

Trigger: Any browser command issued while extension.config has both a defined caCert value and clearCaCert set to true, for example { caCert: '/etc/ssl/corp-ca.pem', clearCaCert: true }. configArgs() runs while building the command line, so the throw fires on the first tool call, before the sandbox or browser is touched. The guard checks caCert !== undefined, so an empty string still triggers it.

Common situations: Persisted or layered config where a stale caCert string survives a merge (defaults plus user settings plus environment) while clearCaCert: true is added later to remove the cert; switching a shared config template from set-cert to clear-cert without deleting the old key; generated CI config that carries both keys because one layer sets a cert and another clears it.

Related errors

AI-assisted analysis of vercel-labs/agent-browser@f9a6cc3421 (2026-08-23). Data as JSON: /api/errors/775c064de039400d. Report an issue: GitHub.