What causes "missing ${name}" in paperclipai/paperclip?

Supply a value after each flag: eval-session --request /path/to/request.json --output /path/to/out.json.

missing ${name}

Error message

missing ${name}

What it means

The argument() helper in eval-session.ts (lines 31-36) parses CLI flags of the form --flag <value> for the eval-session CLI entrypoint. It throws 'missing <name>' when the flag has no following token, the following token is itself another --flag, or the value is an empty string. Values are then passed through path resolve(). It is raised by parseEvalSessionCliArgs for --request and --output.

Source

Thrown at packages/paperclip-runner/src/cli/eval-session.ts:45

} from "../live/live-session.js";
import {
  evalSessionUsage,
  expectedEvalSessionDriver,
  parseEvalSessionRequest,
  type EvalSessionRequest,
  type EvalSessionUsage,
} from "./eval-session-contract.js";
import { evalProviderTransportOptions } from "./eval-provider-runtime.js";

interface EvalSessionCliOptions {
  requestPath: string;
  outputPath: string;
}

function argument(args: string[], name: string): string {
  const index = args.indexOf(name);
  const value = index < 0 ? undefined : args[index + 1];
  if (!value || value.startsWith("--")) throw new Error(`missing ${name}`);
  return resolve(value);
}

export function parseEvalSessionCliArgs(args: string[]): EvalSessionCliOptions {
  const allowed = new Set(["--request", "--output"]);
  for (let index = 0; index < args.length; index += 2) {
    if (!allowed.has(args[index] ?? "")) {
      throw new Error(`unknown argument: ${args[index] ?? ""}`);
    }
    if (args[index + 1] === undefined) throw new Error(`missing ${args[index]}`);
  }
  return {
    requestPath: argument(args, "--request"),
    outputPath: argument(args, "--output"),
  };
}

async function sha256(path: string): Promise<string> {

View on GitHub (pinned to 01ad858492)

Solutions

Supply a value after each flag: eval-session --request /path/to/request.json --output /path/to/out.json.
Quote the path and, if it starts with '-', use './-prefixed' or an absolute path so it doesn't look like a flag.
Check shell quoting/variable expansion — an unset variable can collapse to an empty argument.
Inspect the exact argv passed to the CLI in the calling script; fix the flag/value pairing.

Example fix

// before (shell)
node eval-session.js --request --output out.json
// after
node eval-session.js --request ./request.json --output out.json

Defensive patterns

Strategy: validation

Validate before calling

function assertCliArgs(args: string[]): void {
  const allowed = new Set(["--request", "--output"]);
  for (let i = 0; i < args.length; i += 2) {
    const flag = args[i];
    const value = args[i + 1];
    if (!allowed.has(flag)) throw new Error(`unknown argument: ${flag}`);
    if (value === undefined || value === "" || value.startsWith("--")) {
      throw new Error(`missing ${flag}`);
    }
  }
}

Type guard

function hasFlagValue(args: string[], flag: string): boolean {
  const i = args.indexOf(flag);
  const value = i < 0 ? undefined : args[i + 1];
  return typeof value === "string" && value.length > 0 && !value.startsWith("--");
}

Try / catch

try {
  const opts = parseEvalSessionCliArgs(process.argv.slice(2));
  // proceed
} catch (err) {
  if (err instanceof Error && err.message.startsWith("missing ")) {
    console.error(`Usage: eval-session --request <request.json> --output <out.json> (${err.message})`);
    process.exitCode = 2;
  } else throw err;
}

Prevention

Always pass both flags with explicit values in one place (a script or Makefile target).
Quote paths and use absolute or ./-prefixed paths so leading dashes aren't mistaken for flags.
In shell wrappers, check that variables holding paths are non-empty before invoking the CLI.
Keep flag pairs adjacent — never reorder so a flag name lands in a value slot.

When it happens

Trigger: Running the eval-session CLI as `--request --output out.json` (value consumed as a flag), `--request` with nothing after it, `--request ""`, or a path that literally begins with '--' (e.g. '--request --weird-dir/x.json').

Common situations: Forgetting the value for a flag; quoting mistakes in shell scripts leaving an empty argument; paths starting with dashes; reordering flags so one flag's value slot is filled by the next flag name.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-02). Data as JSON: /api/errors/36d1992bb3175b45. Report an issue: GitHub.