openclaw/openclaw · error · Error

output path is required

Error message

output path is required

What it means

Thrown by writeExternalFileWithinOutputRoot when params.path trims to empty. The function writes browser output artifacts (screenshots, PDFs, downloads, traces) to a caller-selected output root and requires a non-empty relative or absolute path. The check runs before rootDir resolution and directory creation.

Source

Thrown at extensions/browser/src/browser/output-files.ts:19

/**
 * Browser output file writer.
 *
 * Validates caller-provided output paths against a root before writing
 * screenshots, PDFs, downloads, or traces to disk.
 */
import path from "node:path";
import { writeExternalFileWithinRoot } from "../sdk-security-runtime.js";
import { ensureOutputDirectory } from "./output-directories.js";

/** Write a browser output file within a caller-selected output root. */
export async function writeExternalFileWithinOutputRoot(params: {
  rootDir?: string;
  path: string;
  write: (filePath: string) => Promise<void>;
}): Promise<string> {
  const outputPath = params.path.trim();
  if (!outputPath) {
    throw new Error("output path is required");
  }

  const rootDir = params.rootDir
    ? path.resolve(params.rootDir)
    : path.dirname(path.resolve(outputPath));
  await ensureOutputDirectory(rootDir);

  const result = await writeExternalFileWithinRoot({
    rootDir,
    path: outputPath,
    write: params.write,
  }).catch((err: unknown) => {
    if (err instanceof Error && (err as NodeJS.ErrnoException).code === "ENOENT") {
      throw new Error("output directory changed while writing file", { cause: err });
    }
    throw err;
  });
  return result.path;

View on GitHub (pinned to 01804a7531)

Solutions

1. Supply a non-empty output path (filename or absolute path) when invoking the browser output action.
2. Validate the resolved path in the caller before dispatching the action.
3. Default to a deterministic filename (e.g. screenshot.png) in the tool layer when the caller omits one.

Example fix

// before
await writeExternalFileWithinOutputRoot({ path: '', write: ... });
// after
await writeExternalFileWithinOutputRoot({ path: 'screenshot.png', write: ... });

function requireOutputPath(p: string | undefined): string {
  const trimmed = (p ?? '').trim();
  if (!trimmed) throw new Error('output path is required');
  return trimmed;
}
// Pass the validated path to writeExternalFileWithinOutputRoot.

function isNonEmptyOutputPath(p: unknown): p is string {
  return typeof p === 'string' && p.trim().length > 0;
}

try {
  await writeExternalFileWithinOutputRoot({ path, write });
} catch (err) {
  if (err instanceof Error && err.message === 'output path is required') {
    path = defaultOutputName(); // e.g. 'screenshot.png'
    return await writeExternalFileWithinOutputRoot({ path, write });
  }
  throw err;
}

When it happens

Trigger: A browser snapshot, screenshot, PDF, or download action invoked with an empty/whitespace output path; tooling that built the path from an empty variable; a caller that omitted the path field.

Common situations: Agents templating the output path from a missing variable; CLI callers that passed --out ""; harnesses that drop the output filename; profile configs with a blank default output directory combined with a missing filename.

Related errors

• output directory changed while writing file
• browser user data directory not found: ${normalizedUserDataD
• browser proxy upload file not found: ${filePath}
• browser.executablePath not found: ${resolved.executablePath}
• Secure Preferences exceeds the 32 MiB inspection limit

AI-assisted analysis of openclaw/openclaw@01804a7531 (2026-08-12). Data as JSON: /api/errors/a757e46fc6cd8745. Report an issue: GitHub.