parallax/jsPDF · error · Error

{methodName} is only available in 'advanced' API mode. You n

Error message

{methodName} is only available in 'advanced' API mode. You need to call advancedAPI() first.

What it means

Several graphics APIs only function when jsPDF is in 'advanced' API mode, which allows arbitrary transforms and pattern fills. The trap `advancedApiModeTrap` (src/jspdf.js:478) checks `apiMode !== ApiMode.ADVANCED` and throws for `addShadingPattern`, `beginTilingPattern`, `endTilingPattern`, and a `text()` call using a Matrix transform (src/jspdf.js:3547). The default mode is 'compat'; you must enter advanced mode via `doc.advancedAPI()` (src/jspdf.js:420) before calling these methods.

Source

Thrown at src/jspdf.js:480

    if (doSwitch) {
      advancedAPI.call(this);
    }

    return this;
  };

  /**
   * @return {boolean} True iff the current API mode is "advanced". See {@link advancedAPI}.
   * @memberof jsPDF#
   * @name isAdvancedAPI
   */
  API.isAdvancedAPI = function() {
    return apiMode === ApiMode.ADVANCED;
  };

  var advancedApiModeTrap = function(methodName) {
    if (apiMode !== ApiMode.ADVANCED) {
      throw new Error(
        methodName +
          " is only available in 'advanced' API mode. " +
          "You need to call advancedAPI() first."
      );
    }
  };

  var roundToPrecision = (API.roundToPrecision = API.__private__.roundToPrecision = function(
    number,
    parmPrecision
  ) {
    var tmpPrecision = precision || parmPrecision;
    if (isNaN(number) || isNaN(tmpPrecision)) {
      throw new Error("Invalid argument passed to jsPDF.roundToPrecision");
    }
    return number.toFixed(tmpPrecision).replace(/0+$/, "");
  });

View on GitHub (pinned to a3930ce03a)

Solutions

Wrap the advanced calls in `doc.advancedAPI(function(d){ ... })` so the mode is set and restored automatically.
Or manually `doc.advancedAPI()` (no callback) before the calls and `doc.compatAPI()` when done — note saveGraphicsState/restoreGraphicsState and form/tiling-pattern blocks must be balanced.
If using `text()` with a Matrix transform, ensure you are inside an advancedAPI block.
Check `doc.isAdvancedAPI()` returns true before invoking the guarded method as a runtime guard.

Example fix

// before
 doc.addShadingPattern('diag', pattern);   // throws in compat mode

// after
 doc.advancedAPI(function (d) {
   d.addShadingPattern('diag', pattern);
 });

Defensive patterns

Strategy: validation

Validate before calling

function runAdvanced(doc, fn) {
  if (typeof doc.advancedAPI !== 'function') throw new Error('advancedAPI unavailable');
  doc.advancedAPI(function (d) { fn(d); });
}
// usage:
runAdvanced(doc, function (d) { d.addShadingPattern('p', pat); });

Type guard

function isAdvancedReady(doc) {
  return typeof doc.isAdvancedAPI === 'function' && doc.isAdvancedAPI();
}

Try / catch

try {
  doc.addShadingPattern(key, pat);
} catch (e) {
  if (/only available in 'advanced' API mode/.test(e.message)) {
    doc.advancedAPI(function (d) { d.addShadingPattern(key, pat); });
  } else throw e;
}

Prevention

Always wrap advanced-only calls inside doc.advancedAPI(function(d){...}).
Remember advancedAPI(callback) reverts to compat after the callback — don't call advanced methods afterward.
Check doc.isAdvancedAPI() before guarded calls when mode is uncertain.

When it happens

Trigger: Calling `doc.addShadingPattern(...)` or `doc.beginTilingPattern(...)` without first calling `doc.advancedAPI()`; calling `doc.text(...)` with a `transform` argument that is a Matrix while still in compat mode; using a plugin/helper that internally calls these methods without documenting the mode requirement.

Common situations: Copying an advanced example into a compat-mode document; a plugin that expects advanced mode but the host app never switches; forgetting that `advancedAPI(callback)` auto-switches back to compat after the callback — calling an advanced method after the callback returns fails.

Related errors

AI-assisted analysis of parallax/jsPDF@a3930ce03a (2026-08-13). Data as JSON: /api/errors/62abc4da85d5ac43. Report an issue: GitHub.