What causes "unknown argument: ${args[index] ?? ""}" in paperclipai/paperclip?

Check the exact invocation: only '--request --output ' are accepted, in flag/value pairs

unknown argument: ${args[index] ?? ""}

Error message

unknown argument: ${args[index] ?? ""}

What it means

parseEvalSessionCliArgs validates CLI flags in strict pairs: every even-indexed argument must be exactly '--request' or '--output'. This error is thrown when a flag outside that allowlist appears in argv, so unknown/misspelled flags fail fast instead of being silently ignored.

Source

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

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> {
  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.",

View on GitHub (pinned to 01ad858492)

Solutions

Check the exact invocation: only '--request <path> --output <path>' are accepted, in flag/value pairs
Fix the typo or remove any unsupported flag from the command line
If a new flag is genuinely needed, add it to the 'allowed' Set and the corresponding return mapping in parseEvalSessionCliArgs (packages/paperclip-runner/src/cli/eval-session.ts:38)
Verify shell quoting/word splitting didn't shift arguments into even positions

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

const allowed = new Set(["--request", "--output"]);
function validateEvalSessionArgs(args: string[]): string | null {
  for (let i = 0; i < args.length; i += 2) {
    if (!allowed.has(args[i] ?? "")) return `unknown argument: ${args[i] ?? ""}`;
    if (args[i + 1] === undefined) return `missing ${args[i]}`;
  }
  return null;
}

Type guard

function isKnownFlag(arg: string | undefined): arg is "--request" | "--output" {
  return arg === "--request" || arg === "--output";
}

Try / catch

try {
  await runEvalSessionCli(args);
} catch (error) {
  if (error instanceof Error && error.message.startsWith("unknown argument:")) {
    console.error(`Usage: eval-session --request <path> --output <path>\n${error.message}`);
    process.exitCode = 1;
    return;
  }
  throw error;
}

Prevention

Only invoke with the documented flags: --request and --output
Wrap the binary in a shell script/npm script that hardcodes the correct flag names
If a value can legitimately start with '--' in your paths, avoid such paths since argument() rejects them
Add a smoke test calling parseEvalSessionCliArgs with your project's canonical invocation

When it happens

Trigger: Calling runEvalSessionCli (or the eval-session binary) with an argv array where args[i] (i even) is not '--request' or '--output' — e.g. typo'd flags like '--request-path', extra flags like '--verbose', or a stray positional value landing in an even slot.

Common situations: Typo in a flag name when invoking the CLI; copy-pasting invocation syntax from another tool; passing extra arguments (e.g. '--json') not supported by this entrypoint; shell word-splitting shifting a value into a flag position.

Related errors

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