run-llama/liteparse · error · Error

invalid header ' ', expected 'Name: Value

Error message

invalid header '${value}', expected 'Name: Value'

What it means

The `--header` CLI option is parsed by collectHeader, which requires the value to contain a `:` separating name and value. A header argument without any colon cannot be split into a name/value pair, so the CLI rejects it with this message showing the expected `Name: Value` shape. This is used when passing headers to a remote OCR HTTP server.

Solutions

  1. Include a colon in the value: `--header "Authorization: Bearer <token>"`.
  2. Quote the whole header argument so the shell does not split on spaces.
  3. Check `liteparse parse --help` for the exact `--header` syntax expected by collectHeader.

Example fix

// before
liteparse parse doc.pdf --header Authorization Bearer tok
// after
liteparse parse doc.pdf --header "Authorization: Bearer tok"
Defensive patterns

Strategy: validation

Validate before calling

function isValidHeader(h) {
  const i = h.indexOf(':');
  return i > 0 && h.slice(0, i).trim() !== '';
}
// before invoking CLI:
if (!headers.every(isValidHeader)) throw new Error('headers must be Name: Value');

Type guard

const isHeaderArg = (v) => typeof v === 'string' && /^[^:\s][^:]*:/.test(v);

Try / catch

try {
  await program.parseAsync(process.argv);
} catch (e) {
  if (e.message.startsWith('invalid header') && !e.message.includes('empty header name')) {
    console.error(`Bad --header value. Use: --header "Name: Value" (${e.message})`);
    process.exit(2);
  }
  throw e;
}

Prevention

When it happens

Trigger: Passing `--header Authorization` (no colon) or a value where the colon was eaten by the shell, e.g. an unquoted or mistyped argument to the `--header` repeatable option in `packages/node/src/cli.ts`.

Common situations: Copy-pasting curl-style header examples into the CLI flag; forgetting quotes around headers containing spaces so the shell splits them; typos like `--header=Authorization-Bearer xyz`.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of run-llama/liteparse@22d2dd8cd7 (2026-09-08). Data as JSON: /api/errors/0cfbe86c8201e95a. Report an issue: GitHub.

Appendix: source

Thrown at packages/node/src/cli.ts:42

    chunks.push(chunk as Buffer);
  }
  const bytes = Buffer.concat(chunks);
  if (bytes.length === 0) {
    throw new Error(
      "no data on stdin (input `-` expects a document piped in, e.g. `curl … | liteparse parse -`)",
    );
  }
  return bytes;
}

/** Collect repeated `--ocr-server-header "Name: Value"` flags into an object. */
function collectHeader(
  value: string,
  previous: Record<string, string> = {},
): Record<string, string> {
  const idx = value.indexOf(":");
  if (idx === -1) {
    throw new Error(`invalid header '${value}', expected 'Name: Value'`);
  }
  const name = value.slice(0, idx).trim();
  if (name === "") {
    throw new Error(`invalid header '${value}', empty header name`);
  }
  previous[name] = value.slice(idx + 1).trim();
  return previous;
}

program
  .command("parse")
  .description("Parse a document and extract text")
  .argument("<file>", "Path to the document file")
  .option("-o, --output <file>", "Output file path")
  .option("--format <format>", 'Output format: json|text|markdown (default: "text")')
  .option(
    "--image-mode <mode>",
    "How to surface raster images in markdown: off|placeholder|embed (default: placeholder)",

View on GitHub (pinned to 22d2dd8cd7)