mozilla/pdf.js · warning · Error

BOM check failed (run `gulp lint-bom --fix` to clear).

Error message

BOM check failed (run `gulp lint-bom --fix` to clear).

What it means

The `lint-bom` task scans tracked source files for a leading UTF-8 byte order mark (EF BB BF). If any file starts with a BOM, the task prints each offender and throws, directing the user to `gulp lint-bom --fix`. The fix path strips the first 3 bytes from each offending file in place. This is a repo-hygiene check: BOMs can break concatenation, parsers, and the preprocessor, so PDF.js forbids them. It is a non-fatal lint gate, not a runtime defect.

Source

Thrown at gulpfile.mjs:2568

  // Don't exhaust file descriptors.
  const offenders = [];
  for (let i = 0; i < files.length; i += 256) {
    const chunk = files.slice(i, i + 256);
    const flags = await Promise.all(chunk.map(hasBOM));
    chunk.forEach((file, j) => flags[j] && offenders.push(file));
  }
  offenders.sort();

  if (offenders.length === 0) {
    console.log("files checked, no errors found");
    return;
  }

  if (!process.argv.includes("--fix")) {
    for (const file of offenders) {
      console.log(`  Unexpected byte order mark: ${file}`);
    }
    throw new Error("BOM check failed (run `gulp lint-bom --fix` to clear).");
  }

  // Strip the BOM on disk and let the user stage the change.
  await Promise.all(
    offenders.map(async file => {
      const content = await fs.promises.readFile(file);
      await fs.promises.writeFile(file, content.subarray(3));
      console.log(`  removed byte order mark: ${file}`);
    })
  );
  console.log(`done: ${offenders.length} file(s) updated`);
});

gulp.task("lint", function (done) {
  console.log("\n### Linting JS/CSS/JSON/SVG/HTML files");

  // Ensure that we lint the Firefox specific *.jsm files too.
  const esLintOptions = [

View on GitHub (pinned to 5903d58d58)

Solutions

1. Run `gulp lint-bom --fix` — it strips the BOM from every offending file; then stage the change.
2. Configure your editor to save UTF-8 without BOM (VS Code: 'UTF-8', not 'UTF-8 with BOM').
3. Add the lint-bom check (or a pre-commit hook) so BOMs are caught before push.
4. If only one file is flagged, reopen and re-save it as UTF-8 (no BOM) manually.

Example fix

# before
gulp lint-bom        # throws, lists offenders
# after
gulp lint-bom --fix  # strips BOM, prints 'done: N file(s) updated'
git add -u

import { open } from 'fs/promises';
async function hasBOM(file) {
  const h = await open(file, 'r');
  try {
    const { bytesRead, buffer } = await h.read(Buffer.alloc(3), 0, 3, 0);
    return bytesRead === 3 && buffer[0] === 0xef && buffer[1] === 0xbb && buffer[2] === 0xbf;
  } finally { await h.close(); }
}
// fail-fast in a pre-commit hook:
for (const f of stagedFiles) if (await hasBOM(f)) throw new Error(`${f} has a BOM; save as UTF-8 without BOM`);

When it happens

Trigger: An editor or tool (Notepad, some Windows tools, certain PowerShell redirects) saved a source file with a UTF-8 BOM; a copied/pasted file retained a BOM; a generated file written with `utf-8` instead of `utf-8` without BOM; the BOM was introduced by an external commit that wasn't linted.

Common situations: Contributors on Windows; merging generated artifacts; CI gating a PR on `gulp lint` which transitively runs lint-bom.

Related errors

• Unknown encoding format: ${format} in CFF
• Invalid entry in 'Differences' array: ${data}
• Encoding is not a Name nor a Dict

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