mozilla/pdf.js · error · Error

Unknown CMap name: ${name}

Error message

Unknown CMap name: ${name}

What it means

Thrown by createBuiltInCMap when the requested CMap name is neither Identity-H/Identity-V nor present in the hard-coded BUILT_IN_CMAPS list. pdf.js only knows a fixed set of Adobe CMaps; any other name is rejected before any fetch is attempted, so configuring cMapUrl cannot fix an unknown name.

Source

Thrown at src/core/cmap.js:679

  // Merge the map into the current one, making sure not to override
  // any previously defined entries.
  cMap.useCMap.forEach(function (key, value) {
    if (!cMap.contains(key)) {
      cMap.mapOne(key, value);
    }
  });

  return cMap;
}

async function createBuiltInCMap(name, fetchBuiltInCMap) {
  if (name === "Identity-H") {
    return new IdentityCMap(false, 2);
  } else if (name === "Identity-V") {
    return new IdentityCMap(true, 2);
  }
  if (!BUILT_IN_CMAPS.includes(name)) {
    throw new Error("Unknown CMap name: " + name);
  }
  if (!fetchBuiltInCMap) {
    throw new Error("Built-in CMap parameters are not provided.");
  }

  const { cMapData, isCompressed } = await fetchBuiltInCMap(name);
  const cMap = new CMap(true);

  if (isCompressed) {
    return new BinaryCMapReader().process(cMapData, cMap, useCMap =>
      extendCMap(cMap, fetchBuiltInCMap, useCMap)
    );
  }
  const lexer = new Lexer(new Stream(cMapData));
  return parseCMap(cMap, lexer, fetchBuiltInCMap, null);
}

class CMapFactory {

View on GitHub (pinned to 5903d58d58)

Solutions

  1. Update pdf.js to the latest release so BUILT_IN_CMAPS includes more Adobe names.
  2. Repair the PDF so the font uses a standard Adobe CMap that pdf.js recognises.
  3. Catch the error and fall back to a substitute font / no-CID mapping.
  4. If you embed pdf.js in a custom worker, supply a fetchBuiltInCMap that resolves the custom name to your own .bcmap data (still requires the name to be in BUILT_IN_CMAPS, so patching may be needed).
Defensive patterns

Strategy: try-catch

Validate before calling

// Best-effort: pdf.js does not export BUILT_IN_CMAPS, so wrap the call.
// If you maintain a fork, export the list and pre-check:
const KNOWN = new Set(['Identity-H', 'Identity-V', /* ...Adobe names... */]);
function isKnownCMapName(name) {
  return KNOWN.has(name);
}

Try / catch

try {
  cmap = await CMapFactory.create({ encoding, fetchBuiltInCMap, useCMap });
} catch (e) {
  if (/Unknown CMap name/.test(e.message)) {
    console.warn('CMap name not bundled, falling back', e);
    cmap = null;
  } else throw e;
}

Prevention

When it happens

Trigger: A PDF font references a CMap name (via /Encoding /Some-Name or a ToUnicode usecmap) that is not in pdf.js's BUILT_IN_CMAPS list - e.g. a custom, third-party, or newer Adobe CMap that this build does not recognize.

Common situations: Outdated pdf.js build missing newer Adobe CMap names; a PDF that references a private/non-Adobe CMap; a typo or corruption in the CMap name inside the font dictionary.

Related errors

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