parallax/jsPDF · error · Error

Invalid argument passed to jsPDF.addField.

Error message

Invalid argument passed to jsPDF.addField.

What it means

jsPDF.addField() registers an AcroForm field into the PDF document. It uses instanceof AcroFormField to verify the argument is a proper form field object created through the AcroForm API (e.g., new AcroFormTextField(), new AcroFormCheckBox()). Plain objects or field-like literals will fail this check because they lack the internal prototype chain and initialization that AcroFormField provides.

Source

Thrown at src/modules/acroform.js:3146

// Public:

/**
 * Add an AcroForm-Field to the jsPDF-instance
 *
 * @name addField
 * @function
 * @instance
 * @param {Object} fieldObject
 * @returns {jsPDF}
 */
var addField = (jsPDFAPI.addField = function(fieldObject) {
  initializeAcroForm(this, fieldObject);

  if (fieldObject instanceof AcroFormField) {
    putForm(fieldObject);
  } else {
    throw new Error("Invalid argument passed to jsPDF.addField.");
  }
  fieldObject.page = fieldObject.scope.internal.getCurrentPageInfo().pageNumber;
  return this;
});

jsPDFAPI.AcroFormChoiceField = AcroFormChoiceField;
jsPDFAPI.AcroFormListBox = AcroFormListBox;
jsPDFAPI.AcroFormComboBox = AcroFormComboBox;
jsPDFAPI.AcroFormEditBox = AcroFormEditBox;
jsPDFAPI.AcroFormButton = AcroFormButton;
jsPDFAPI.AcroFormPushButton = AcroFormPushButton;
jsPDFAPI.AcroFormRadioButton = AcroFormRadioButton;
jsPDFAPI.AcroFormCheckBox = AcroFormCheckBox;
jsPDFAPI.AcroFormTextField = AcroFormTextField;
jsPDFAPI.AcroFormPasswordField = AcroFormPasswordField;
jsPDFAPI.AcroFormAppearance = AcroFormAppearance;

jsPDFAPI.AcroForm = {

View on GitHub (pinned to a3930ce03a)

Solutions

  1. Create fields using the provided constructors: var field = new doc.AcroFormTextField() or new AcroFormCheckBox()
  2. Ensure you import AcroFormField subclasses from the same jsPDF instance that addField is called on
  3. Do not serialize/deserialize field objects; reconstruct them from data
  4. If using multiple jsPDF bundles, ensure field objects and addField come from the same bundle instance

Example fix

// before
doc.addField({ fieldName: 'myField', FT: '/Tx' }); // throws

// after
var textField = new doc.AcroFormTextField();
textField.fieldName = 'myField';
doc.addField(textField);
Defensive patterns

Strategy: type-guard

Validate before calling

// Verify field is an AcroFormField before calling addField
function isAcroFormField(obj, jsPDFInstance) {
  // Check for the constructor name or key AcroFormField properties
  return obj instanceof jsPDFInstance.AcroFormFieldConstructor ||
    (obj && typeof obj === 'object' && 'FT' in obj && 'fieldName' in obj);
}

// Safer: always create via constructors
var field = new doc.AcroFormTextField();
doc.addField(field);

Type guard

/**
 * Check if object is likely an AcroFormField instance
 * @param {*} obj
 * @returns {boolean}
 */
function looksLikeAcroFormField(obj) {
  return obj != null &&
    typeof obj === 'object' &&
    typeof obj.hasOwnProperty === 'function' &&
    ('FT' in obj || 'fieldName' in obj || 'partialFieldNames' in obj);
}

Try / catch

try {
  doc.addField(fieldObject);
} catch (e) {
  console.error('addField failed - object is not an AcroFormField:', e.message);
  // Reconstruct the field properly
  var newField = new doc.AcroFormTextField();
  Object.assign(newField, fieldObject);
  doc.addField(newField);
}

Prevention

When it happens

Trigger: Calling doc.addField({}) or doc.addField(plainObject). Calling doc.addField(new SomeCustomClass()) that is not a subclass of AcroFormField. Creating fields with Object.create() without proper prototype linkage. Importing field objects from JSON (deserialization loses the prototype chain).

Common situations: Developers trying to construct field objects manually instead of using the factory constructors. Serializing fields to JSON and deserializing them, which strips the instanceof relationship. Using a different/older version of jsPDF where the AcroFormField class reference differs.

Related errors

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