mozilla/pdf.js · error · Error

Must use the same `intent`-argument when calling the `PDFPag

Error message

Must use the same `intent`-argument when calling the `PDFPageProxy.render` and `PDFDocumentProxy.getOptionalContentConfig` methods.

What it means

A generic Error during PDFPageProxy.render: the optionalContentConfig passed in (or the auto-generated one) was built for a renderingIntent whose bitmask does not overlap the current render's renderingIntent. The two must be derived from the same intent (display vs print) so that optional-content (OCG/OCMD) visibility matches. Typically happens when a caller pre-creates getOptionalContentConfig({intent:'display'}) and passes that promise to render({intent:'print'}).

Source

Thrown at src/display/api.js:1663

      operationsFilter,
    });

    (intentState.renderTasks ||= new Set()).add(internalRenderTask);
    const renderTask = internalRenderTask.task;

    Promise.all([
      intentState.displayReadyCapability.promise,
      optionalContentConfigPromise,
    ])
      .then(([transparency, optionalContentConfig]) => {
        if (this.destroyed) {
          complete();
          return;
        }
        this._stats?.time("Rendering");

        if (!(optionalContentConfig.renderingIntent & renderingIntent)) {
          throw new Error(
            "Must use the same `intent`-argument when calling the `PDFPageProxy.render` " +
              "and `PDFDocumentProxy.getOptionalContentConfig` methods."
          );
        }
        internalRenderTask.initializeGraphics({
          transparency,
          optionalContentConfig,
        });
        internalRenderTask.operatorListChanged();
      })
      .catch(complete);

    return renderTask;
  }

  /**
   * @param {GetOperatorListParameters} params - Page getOperatorList
   *   parameters.

View on GitHub (pinned to 5903d58d58)

Solutions

1. Pass the same intent string to both getOptionalContentConfig({intent}) and render({intent}).
2. Omit optionalContentConfigPromise and let render() auto-generate one matching its own intent.
3. Create a fresh getOptionalContentConfig promise each time the render intent changes.

Example fix

// before
const occ = await doc.getOptionalContentConfig({ intent: 'display' });
await page.render({ canvasContext, intent: 'print', optionalContentConfigPromise: Promise.resolve(occ) }).promise; // throws

// after
const occPromise = doc.getOptionalContentConfig({ intent: 'print' });
await page.render({ canvasContext, intent: 'print', optionalContentConfigPromise: occPromise }).promise;

// Ensure the render intent matches the optional-content config intent.
function renderWithIntent(page, ctx, intent) {
  const occPromise = page._transport
    ? page._transport.getOptionalContentConfig(
        page._transport.getRenderingIntent(intent).renderingIntent
    )
    : null;
  return page.render({ canvasContext: ctx, intent, optionalContentConfigPromise: occPromise });
}

When it happens

Trigger: Passing an optionalContentConfigPromise created with intent 'display' to a render call with intent 'print' (or vice versa); mixing a cached optional-content config across display and print renders; reusing a stale promise from a previous render with a different intent.

Common situations: Custom viewers that pre-cache OCG state for performance; print workflows that reuse the on-screen OCG config; refactoring that changed the intent string in one place but not the other.

Related errors

• Image exceeded maximum allowed size and was removed.
• Unable to decode inline image: "${reason}".
• Type3 font load error: ${reason}
• Unknown PatternType: ${typeNum}
• Unknown PatternName: ${patternName}

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