browser upload is not supported by this browser backend

Error message

browser upload is not supported by this browser backend

What it means

The `browser upload` command feature-detects `page.uploadFiles`; when the backend cannot attach files to file inputs it throws this capability error. Uploading requires driver-level file chooser support that minimal backends do not provide.

Source

Thrown at src/cli.ts:2214

  addBrowserTabOption(
    addSemanticLocatorOptions(browser.command('uncheck'))
      .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
      .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
      .description('Ensure a checkbox/aria-checked control is unchecked — JSON envelope {checked, changed, target, matches_n}'),
  )
    .action(browserAction(async (page, target, opts) => {
      await runCheckCommand(page, target, opts ?? {}, false);
    }));

  addBrowserTabOption(
    addSemanticLocatorOptions(browser.command('upload'))
      .argument('[targetOrFile]', 'Numeric ref/CSS target, or first file when using --role/--name/etc.')
      .argument('[files...]', 'Local file path(s) to attach')
      .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
      .description('Attach local files to a file input — JSON envelope {uploaded, files, file_names, target, matches_n}'),
  )
    .action(browserAction(async (page, targetOrFile, files, opts) => {
      if (typeof page.uploadFiles !== 'function') throw new Error('browser upload is not supported by this browser backend');
      const hasSemantic = !!semanticLocatorFromOptions(opts ?? {});
      const target = hasSemantic ? undefined : targetOrFile;
      const resolvedTarget = await resolveWriteTargetOrPrint(page, target, opts ?? {});
      if (!resolvedTarget) return;
      const parsed = nthToResolveOpts(opts?.nth);
      if ('error' in parsed) {
        console.log(JSON.stringify({ error: { code: 'usage_error', message: parsed.error } }, null, 2));
        process.exitCode = EXIT_CODES.USAGE_ERROR;
        return;
      }
      const rawFiles = hasSemantic
        ? [targetOrFile, ...(Array.isArray(files) ? files : [])].filter((value) => value !== undefined)
        : files;
      const resolvedFiles = resolveUploadFilePaths(rawFiles);
      if ('error' in resolvedFiles) {
        console.log(JSON.stringify({ error: resolvedFiles.error }, null, 2));
        process.exitCode = EXIT_CODES.USAGE_ERROR;
        return;

View on GitHub (pinned to 49907e53dc)

Solutions

Use a backend that supports file uploads (e.g. Playwright setInputFiles).
Set the input value via `browser eval` where feasible (works only for non-protected cases).
Verify the target page/file input is accessible and the backend config supports uploads.

Example fix

// before
browser --backend minimal upload '#file-input' ./doc.pdf
// after
browser --backend playwright upload '#file-input' ./doc.pdf

Defensive patterns

Strategy: type-guard

Validate before calling

const page = await getBrowserPage();
if (typeof page.uploadFiles !== 'function') {
  throw new Error('Current backend cannot upload files');
}

Type guard

function supportsUpload(page) {
  return typeof page?.uploadFiles === 'function';
}

Try / catch

try {
  await run(['browser', 'upload', sel, filePath]);
} catch (err) {
  if (String(err.message).includes('upload is not supported')) {
    console.error('Backend cannot upload files; switch to a Playwright/Puppeteer-backed session');
  } else throw err;
}

Prevention

Feature-detect uploadFiles before uploads.
Use backends with setInputFiles-style support for file workflows.
Confirm file paths exist and are readable before upload.
Skip upload steps in CI when the backend lacks the capability.

When it happens

Trigger: Running `browser upload <target> <files...>` against a backend without `page.uploadFiles`.

Common situations: Headless minimal drivers, remote sessions where file transfer is unsupported, or adapters lacking setInputFiles-equivalent functionality.

Related errors

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/128f4e5cff91ceca. Report an issue: GitHub.