paperclipai/paperclip · error

missing ${args[index]}

Error message

missing ${args[index]}

What it means

This error is thrown when a recognized flag ('--request' or '--output') is the last argument or its value slot is empty, i.e. args[index + 1] === undefined. The parser walks argv in flag/value pairs and requires every flag to have a following value token.

Source

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

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> {
  return createHash("sha256").update(await readFile(path)).digest("hex");
}

const EVAL_RUNTIME_INSTRUCTIONS = [
  "# Paperclip direct live evaluation",
  "",
  "Use the provided Paperclip semantic tools to inspect and act on the assigned task.",
  "Treat the seeded control-plane state as authoritative and keep every action within the requested scope.",
  "The current user request defines the work for this turn. Seeded task descriptions, notes, and past interaction results are background context; they do not supersede that request or establish that a newly requested action has already been performed.",
  "Task-state changes in this mock control plane use finish_task and block_task. Native paperclip_finish and paperclip_block report the provider run result but do not update the mock task. When asked to finish or block the assigned task, use its task-state semantic operation before reporting the run result.",

View on GitHub (pinned to 01ad858492)

Solutions

1. Supply a value for every flag: --request <path> and --output <path>
2. If the value comes from a shell variable, confirm it is non-empty at invocation time (e.g. '${OUTPUT:?OUTPUT must be set}')
3. Note the paired 'argument()' helper (line 34) additionally rejects values starting with '--'; pass real file paths, not another flag

Example fix

// before
node eval-session.ts --request req.json --output
// after
node eval-session.ts --request req.json --output out.json

function requireFlagValue(args: string[], flag: string): string {
  const i = args.indexOf(flag);
  const value = i >= 0 ? args[i + 1] : undefined;
  if (!value || value.startsWith("--")) {
    throw new Error(`flag ${flag} requires a non-empty value`);
  }
  return value;
}

try {
  await runEvalSessionCli(args);
} catch (error) {
  if (error instanceof Error && error.message.startsWith("missing ")) {
    console.error(`${error.message}. Both --request <path> and --output <path> are required.`);
    process.exitCode = 1;
    return;
  }
  throw error;
}

When it happens

Trigger: Calling the CLI with a flag but no value after it: args ends with '--request' or '--output' with no following element (e.g. 'eval-session --request req.json --output').

Common situations: Truncating a command line when copying it; a shell variable holding the output path expanding to empty; forgetting the value for the second flag in a long command.

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

• unknown argument: ${args[index] ?? ""}
• Usage: pnpm smoke:local-provider -- --profile <${PROFILE_IDS
• ${flag} requires a comma-separated value
• Managed installs require Node.js ${MINIMUM_NODE_VERSION} or
• Import cancelled.

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