mozilla/pdf.js · error · JpegError

Only single frame JPEGs supported

Error message

Only single frame JPEGs supported

What it means

Thrown by parse() if a SOF (Start-Of-Frame) marker (0xFFC0/C1/C2) is encountered when a frame has already been established. PDF.js only supports single-frame (non-hierarchical) JPEGs; a second SOF indicates hierarchical or animated JPEG which the decoder cannot handle.

Source

Thrown at src/core/jpg.js:1003

            } else if (quantizationTableSpec >> 4 === 1) {
              // 16 bit values
              for (j = 0; j < 64; j++) {
                z = dctZigZag[j];
                tableData[z] = view.getUint16(offset);
                offset += 2;
              }
            } else {
              throw new JpegError("DQT - invalid table spec");
            }
            quantizationTables[quantizationTableSpec & 15] = tableData;
          }
          break;

        case 0xffc0: // SOF0 (Start of Frame, Baseline DCT)
        case 0xffc1: // SOF1 (Start of Frame, Extended DCT)
        case 0xffc2: // SOF2 (Start of Frame, Progressive DCT)
          if (frame) {
            throw new JpegError("Only single frame JPEGs supported");
          }
          offset += 2; // Skip marker length.

          frame = {};
          frame.extended = fileMarker === 0xffc1;
          frame.progressive = fileMarker === 0xffc2;
          frame.precision = data[offset++];
          const sofScanLines = view.getUint16(offset);
          offset += 2;
          frame.scanLines = dnlScanLines || sofScanLines;
          frame.samplesPerLine = view.getUint16(offset);
          offset += 2;
          frame.components = [];
          frame.componentIds = {};
          const componentsCount = data[offset++];
          let maxH = 0,
            maxV = 0;
          for (i = 0; i < componentsCount; i++) {

View on GitHub (pinned to 5903d58d58)

Solutions

1. Re-encode the image as a single-frame baseline or progressive JPEG.
2. If hierarchical JPEG is genuinely needed, pre-flatten it with an external tool before embedding.
3. Catch JpegError and fall back to a placeholder or external decoder.

try { jpegImg.parse(data); }
catch (e) { if (e.name === 'JpegError' && /single frame/.test(e.message)) { /* multi-frame JPEG unsupported */ } else throw e; }

When it happens

Trigger: The marker loop sees a second SOFn marker after `frame` is already set. The guard `if (frame)` at the top of the SOFn case triggers the throw.

Common situations: Hierarchical-mode JPEG (rare), or a JPEG stream that accidentally concatenated two images. Some motion-JPEG or multi-frame containers embed multiple SOFs. Almost never seen in well-formed PDFs.

Related errors

• SOI not found
• Duplicate EXIF-blocks found.
• JpegImage.parse - unknown marker: ${fileMarker.toString(16)}
• JpegImage.parse - no frame data found.
• invalid huffman sequence

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