What causes "--index was given without a value" in mozilla/pdf.js?

Provide a real path: `gulp test --code=foo --index=/path/to/ccov/index.json`, or drop `--index` entirely to use the auto-downloaded index.

mozilla/pdf.js · error · Error

--index was given without a value

Error message

--index was given without a value

What it means

During coverage-driven test selection, gulpfile.mjs reads an optional `--index=<path>` argument that points to a local coverage_search index (used read-only instead of downloading the published one). `getArgValue('--index')` returns the empty string only when the flag was explicitly passed with no value (e.g. `--index=` from an unset shell variable like `$PDFJS_CCOV_INDEX`). An empty value is treated as a mistake — silently falling back to the downloaded index would hide a misconfigured pipeline, so the build fails loudly.

Source

Thrown at gulpfile.mjs:886

      }
    }
  }
}

// Builds the coverage_search command line. By default the published index is
// downloaded; an explicit --index=<path> selects a local index instead, used
// read-only so it's never overwritten by the published copy.
function getCoverageSearchArgs(codeArg) {
  const searchArgs = [
    path.join(__dirname, "external/ccov/coverage_search.mjs"),
    `--code=${codeArg}`,
  ];
  const indexArg = getArgValue("--index");
  if (indexArg === "") {
    // An explicit but empty value (e.g. an unset shell variable expanding to
    // `--index=`) almost certainly isn't intended; fail loudly rather than
    // silently falling back to the downloaded index.
    throw new Error("--index was given without a value");
  }
  if (indexArg) {
    searchArgs.push(`--index=${indexArg}`, "--no-download");
  } else if (process.argv.includes("--no-download")) {
    searchArgs.push("--no-download");
  }
  return searchArgs;
}

// Returns the set of test IDs defined in the local ref-test manifest, or null
// when it can't be read. Used to drop coverage-derived IDs that don't exist on
// this branch (e.g. a test renamed since the published index was built), which
// would otherwise make test.mjs reject the entire run.
function readManifestTestIds() {
  try {
    const manifestFile = process.env.PDF_TEST || "test_manifest.json";
    const manifest = JSON.parse(
      fs.readFileSync(path.join(__dirname, TEST_DIR, manifestFile), "utf8")

View on GitHub (pinned to 5903d58d58)

Solutions

Provide a real path: `gulp test --code=foo --index=/path/to/ccov/index.json`, or drop `--index` entirely to use the auto-downloaded index.
If driven by an env var, default it: `--index=${INDEX_FILE:-./external/ccov/index.json}` or omit the flag when empty.
Check for stray `=` or empty quotes in your shell invocation.
Audit the CI job that sets the index variable (it may be gated on the wrong condition).

Example fix

# before
gulp test --code=$CODE --index=$INDEX_FILE   # $INDEX_FILE unset -> '--index='
# after
INDEX_FILE=${INDEX_FILE:-}
gulp test --code=$CODE ${INDEX_FILE:+--index=$INDEX_FILE}

Defensive patterns

Strategy: validation

Validate before calling

// Validate the --index argv before letting gulpfile parse it.
function validateIndexArg(argv) {
  const i = argv.indexOf('--index');
  if (i === -1) return null;
  const next = argv[i + 1];
  const inline = argv[i].startsWith('--index=') ? argv[i].slice(8) : next;
  if (!inline) throw new Error('--index requires a non-empty path');
  return inline;
}

Try / catch

try {
  runGulp('test', ['--code', code, `--index=${idx}`]);
} catch (e) {
  if (/--index was given without a value/.test(e.message)) {
    runGulp('test', ['--code', code]); // fall back to downloaded index
  } else throw e;
}

Prevention

Use shell parameter expansion to omit empty values: `${IDX:+--index=$IDX}`.
Document that `--index=` with no value is an error, not a default.
Default unset env vars explicitly in CI YAML before passing to gulp.

When it happens

Trigger: Invoking the coverage test task with `--index=` (trailing equals, no path); an env var like `--index=$INDEX_FILE` where `$INDEX_FILE` is unset; quoting that strips the value (`--index=""`).

Common situations: CI scripts that conditionally pass `--index` driven by an env var that is not set on this branch/job; copy-pasting a command template and forgetting to fill in the path.

Related errors

AI-assisted analysis of mozilla/pdf.js@5903d58d58 (2026-08-13). Data as JSON: /api/errors/c157397baf9255c6. Report an issue: GitHub.