What causes "Invalid system dependency name: ${JSON.stringify(name)}" in vercel-labs/agent-browser?

Pass bare dnf package names only: trim the string and strip version constraints, globs, and architecture suffix qualifiers that contain @ : / or spaces (letters, digits, dot, plus, hyphen, underscore are accepted).

vercel-labs/agent-browser · error

Invalid system dependency name: ${JSON.stringify(name)}

Error message

Invalid system dependency name: ${JSON.stringify(name)}

What it means

formatDnfPackageName (vercel.ts:351-355) validates each entry of options.systemDependencies against SAFE_DNF_PACKAGE_NAME (/^[A-Za-z0-9._+][A-Za-z0-9._+-]*$/, vercel.ts:50) before splicing names into the `dnf install` shell line (vercel.ts:126-129). Names are interpolated into a shell command, so anything that is not a bare RPM package name, including version constraints, globs, whitespace, or a leading dash, throws. JSON.stringify in the message shows the exact rejected value.

Source

Thrown at packages/@agent-browser/sandbox/src/vercel.ts:353

    );
  })) as Record<string, unknown>;
  const Sandbox = mod.Sandbox;
  if (typeof Sandbox !== "function" && typeof Sandbox !== "object") {
    throw new Error("@vercel/sandbox did not export Sandbox.");
  }
  return Sandbox as VercelSandboxConstructor;
}

function defaultEnv(): Readonly<Record<string, string | undefined>> {
  const globalWithProcess = globalThis as typeof globalThis & {
    readonly process?: { readonly env?: Readonly<Record<string, string | undefined>> };
  };
  return globalWithProcess.process?.env ?? {};
}

function formatDnfPackageName(name: string): string {
  if (!SAFE_DNF_PACKAGE_NAME.test(name)) {
    throw new Error(`Invalid system dependency name: ${JSON.stringify(name)}`);
  }
  return quoteShellArg(name);
}

View on GitHub (pinned to 548b159b30)

Solutions

Pass bare dnf package names only: trim the string and strip version constraints, globs, and architecture suffix qualifiers that contain @ : / or spaces (letters, digits, dot, plus, hyphen, underscore are accepted).
Use the built-in default list: omit systemDependencies (it defaults to CHROMIUM_SYSTEM_DEPS in vercel.ts:22-48) and only override it with a curated array of bare names.
If the value came from config/user input, validate each name against /^[A-Za-z0-9._+][A-Za-z0-9._+-]*$/ (plus .trim()) before handing it to withAgentBrowserSandbox/createAgentBrowserSnapshot, and reject early with your own error naming the index.
When you truly need a versioned install, pre-install that package yourself via sandbox.runCommand("dnf", [...]) with explicit args instead of relying on systemDependencies.

Example fix

// before
await createAgentBrowserSandbox({
  systemDependencies: ["nss >= 3.79", "gtk3"],
});

// after
await createAgentBrowserSandbox({
  systemDependencies: ["nss", "gtk3"],
});

Defensive patterns

Strategy: validation

Validate before calling

const SAFE_DNF_PACKAGE_NAME = /^[A-Za-z0-9._+][A-Za-z0-9._+-]*$/;

function normalizeSystemDependencies(names: readonly string[]): readonly string[] {
  return names.map((name) => {
    const trimmed = name.trim();
    if (!SAFE_DNF_PACKAGE_NAME.test(trimmed)) {
      throw new Error(`Invalid system dependency name: ${JSON.stringify(trimmed)}`);
    }
    return trimmed;
  });
}

// run BEFORE withAgentBrowserSandbox / createAgentBrowserSandbox
const deps = normalizeSystemDependencies(["nss", "gtk3"]);

Type guard

function isSafeDnfPackageName(name: string): boolean {
  return /^[A-Za-z0-9._+][A-Za-z0-9._+-]*$/.test(name);
}

function assertSafeSystemDependencies(names: readonly string[]): void {
  names.forEach((name, index) => {
    if (!isSafeDnfPackageName(name)) {
      throw new Error(`systemDependencies[${index}] is not a bare dnf package name: ${name}`);
    }
  });
}

Try / catch

try {
  await createAgentBrowserSandbox({ systemDependencies: deps });
} catch (error) {
  if (error instanceof Error && error.message.startsWith("Invalid system dependency name:")) {
    // message carries JSON.stringify(name); surface it to config validation, do not retry
    throw new Error(`Fix systemDependencies config: ${error.message}`);
  }
  throw error;
}

Prevention

Default to the built-in CHROMIUM_SYSTEM_DEPS list; only override with bare package names copied from `dnf list` output, not from Dockerfile spec strings.
Never put version constraints, globs, or npm-style name@version entries in systemDependencies; pre-install versioned packages via sandbox.runCommand instead.
Trim config-sourced strings and validate against /^[A-Za-z0-9._+][A-Za-z0-9._+-]*$/ at config load time so bad names fail at startup with an index.
Treat this throw as a security guard: it blocks shell injection, so never try to quote or escape your way around it.

When it happens

Trigger: Passing systemDependencies entries such as "nss >= 3.0" (spaces and comparison operators), "nss*" (glob), "" (empty string fails the first-character class), "-flag" (leading dash), "chromium@latest" or "group:base" (@ and : are not allowed), or a name with trailing whitespace. The default CHROMIUM_SYSTEM_DEPS list always passes; only user-supplied systemDependencies arrays can trigger it.

Common situations: Copying dnf/apt spec strings from Dockerfiles (e.g. `nss-3.90.0-1.el9.x86_64` is fine but `nss >= 3.79` is not); npm-style package@version habits; forgetting installSystemDependencies exists and hand-rolling dependency lists from documentation snippets; untrimmed strings from config files.

Related errors

AI-assisted analysis of vercel-labs/agent-browser@548b159b30 (2026-08-16). Data as JSON: /api/errors/c1206df193517598. Report an issue: GitHub.