run-llama/liteparse · error · Error

invalid header ' ', empty header name

Error message

invalid header '${value}', empty header name

What it means

collectHeader splits the `--header` value on the first `:` and trims the left side; if the resulting header name is empty (e.g. the value starts with `:`), the header is meaningless and the CLI throws. This guards against silently sending malformed headers to an OCR HTTP server.

Solutions

  1. Provide a non-empty name before the colon: `--header "Authorization: Bearer <token>"`.
  2. If building headers from shell variables, verify the variable is non-empty before invoking the CLI.
  3. Log/echo the fully assembled argument list in scripts to catch variables that expanded to nothing.

Example fix

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

Strategy: validation

Validate before calling

function hasHeaderName(h) {
  const i = h.indexOf(':');
  return i !== -1 && h.slice(0, i).trim() !== '';
}
if (!hasHeaderName(flagValue)) throw new Error('header name must be non-empty: ' + flagValue);

Type guard

const hasNonEmptyName = (v) => typeof v === 'string' && v.includes(':') && v.slice(0, v.indexOf(':')).trim() !== '';

Try / catch

try {
  await program.parseAsync(process.argv);
} catch (e) {
  if (e.message.includes('empty header name')) {
    console.error(`--header value "${flagValue}" is missing a name before the colon.`);
    process.exit(2);
  }
  throw e;
}

Prevention

When it happens

Trigger: Passing `--header ": value"`, `--header ':'`, or a value like `": Bearer x"` where the shell or a quoting mistake dropped the header name before the colon.

Common situations: Quoting mistakes where a variable containing the header name expanded to empty (`--header "$AUTH_HEADER"` when AUTH_HEADER=': x'); hand-editing scripts and accidentally deleting the name.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

    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)",
  )
  .option(
    "--image-output-dir <dir>",
    "Directory to write embedded images to when --image-mode embed is set",

View on GitHub (pinned to 22d2dd8cd7)