mozilla/pdf.js · error · FormatError

Could not fix indexToLocFormat: ${indexToLocFormat}

Error message

Could not fix indexToLocFormat: ${indexToLocFormat}

What it means

Thrown by sanitizeHead() when the head table's indexToLocFormat field is invalid (not 0 or 1) and the code cannot deduce the correct value from the loca table length. The loca table should be either 2*(numGlyphs+1) bytes (short format, indexToLocFormat=0) or 4*(numGlyphs+1) bytes (long format, indexToLocFormat=1); if neither matches, recovery is impossible.

Source

Thrown at src/core/fonts.js:2159

        // consists of long offsets.
        //
        // The number of entries in the loca table should be numGlyphs + 1.
        //
        // Using this information, we can work backwards to deduce if the
        // size of each offset in the loca table, and thus figure out the
        // appropriate value for indexToLocFormat.

        const numGlyphsPlusOne = numGlyphs + 1;
        if (locaLength === numGlyphsPlusOne << 1) {
          // 0x0000 indicates the loca table consists of short offsets
          data[50] = 0;
          data[51] = 0;
        } else if (locaLength === numGlyphsPlusOne << 2) {
          // 0x0001 indicates the loca table consists of long offsets
          data[50] = 0;
          data[51] = 1;
        } else {
          throw new FormatError(
            "Could not fix indexToLocFormat: " + indexToLocFormat
          );
        }
      }
    }

    function sanitizeGlyphLocations(
      loca,
      glyf,
      numGlyphs,
      isGlyphLocationsLong,
      hintsValid,
      dupFirstEntry,
      maxSizeOfInstructions
    ) {
      let itemSize, itemDecode, itemEncode;
      if (isGlyphLocationsLong) {
        itemSize = 4;

View on GitHub (pinned to 5903d58d58)

Solutions

  1. Rebuild the font with fonttools: load and re-save to regenerate consistent head/loca/maxp tables.
  2. Run ots-sanitize or fontbakery to identify and report the specific table inconsistency.
  3. If numGlyphs is wrong, fix the maxp table's numGlyphs value to match the actual loca entry count.
  4. Replace the corrupt embedded font with a clean copy.

Example fix

# rebuild font to fix head/loca/maxp consistency
from fontTools import ttLib
font = ttLib.TTFont('broken.ttf')
# fontTools recalculates loca/head on save
font.save('fixed.ttf')
Defensive patterns

Strategy: validation

Validate before calling

// Server-side: verify head.indexToLocFormat consistency with loca length
// from fontTools import ttLib
// font = ttLib.TTFont('font.ttf')
// numGlyphs = font['maxp'].numGlyphs
// locaLen = len(font['loca'])  # entries
// fmt = font['head'].indexToLocFormat
// if fmt not in (0, 1):
//     if locaLen == numGlyphs + 1: pass  # can infer short
//     elif locaLen == (numGlyphs + 1) * 2: pass  # can infer long
//     else: print('Cannot fix indexToLocFormat')

Try / catch

try {
  await page.render(renderParams).promise;
} catch (err) {
  if (err.message?.includes('Could not fix indexToLocFormat')) {
    console.error('Font head/loca/maxp tables are inconsistent; rebuild the font.');
  } else { throw err; }
}

Prevention

When it happens

Trigger: sanitizeHead detects indexToLocFormat outside [0,1], then checks locaLength against numGlyphsPlusOne<<1 and numGlyphsPlusOne<<2. If neither matches, the throw fires. This means both the head table's indexToLocFormat field and the loca table's actual size are inconsistent with numGlyphs.

Common situations: A TrueType font where the head, loca, and maxp tables are mutually inconsistent (e.g., numGlyphs was changed but loca wasn't rebuilt). Fonts edited by hex-editing tools without rebuilding table offsets. Corrupt fonts where the loca table was truncated. Fonts with a deliberately malformed indexToLocFormat that the sanitizer cannot auto-fix.

Related errors

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