auth0/node-jsonwebtoken · error

"${key}" is not allowed in "${parameterName}"

Error message

"${key}" is not allowed in "${parameterName}"

What it means

When signing, unknown keys are rejected by default in both the options and the payload claims. Any property not present in the library's schema (options) or expected claim validators (payload) triggers this error unless allowUnknown is enabled, protecting against typos in option names and unintended claims.

Source

Thrown at sign.js:51

  allowInvalidAsymmetricKeyTypes: { isValid: isBoolean, message: '"allowInvalidAsymmetricKeyTypes" must be a boolean'}
};

const registered_claims_schema = {
  iat: { isValid: isNumber, message: '"iat" should be a number of seconds' },
  exp: { isValid: isNumber, message: '"exp" should be a number of seconds' },
  nbf: { isValid: isNumber, message: '"nbf" should be a number of seconds' }
};

function validate(schema, allowUnknown, object, parameterName) {
  if (!isPlainObject(object)) {
    throw new Error('Expected "' + parameterName + '" to be a plain object.');
  }
  Object.keys(object)
    .forEach(function(key) {
      const validator = schema[key];
      if (!validator) {
        if (!allowUnknown) {
          throw new Error('"' + key + '" is not allowed in "' + parameterName + '"');
        }
        return;
      }
      if (!validator.isValid(object[key])) {
        throw new Error(validator.message);
      }
    });
}

function validateOptions(options) {
  return validate(sign_options_schema, false, options, 'options');
}

function validatePayload(payload) {
  return validate(registered_claims_schema, true, payload, 'payload');
}

const options_to_payload = {

View on GitHub (pinned to b924272f29)

Solutions

  1. Fix the option/claim spelling to one the library knows (expiresIn, notBefore, audience, issuer, subject, jwtid, keyid, header, etc.)
  2. Remove unrelated keys from the options object — only jwt.sign options belong there
  3. Move custom claims into a dedicated claims object within the payload as intended
  4. If a key is intentional, restructure so it goes through the documented API (e.g. header via the header option)

Example fix

// before
jwt.sign(payload, secret, { expireIn: '1h' });
// after
jwt.sign(payload, secret, { expiresIn: '1h' });
Defensive patterns

Strategy: validation

Validate before calling

const SIGN_OPTIONS = ['algorithm','expiresIn','notBefore','audience','issuer','subject','jwtid','keyid','header','noTimestamp','allowInsecureKeySizes','mutatePayload','allowInvalidAsymmetricKeyTypes','encoding','clockTimestamp'];
function assertKnownOptions(opts) {
  for (const k of Object.keys(opts || {})) {
    if (!SIGN_OPTIONS.includes(k)) throw new Error('Unknown sign option: ' + k + ' (typo?)');
  }
}
assertKnownOptions(options);

Type guard

function hasOnlyKnownKeys(obj, known) {
  return Object.keys(obj || {}).every(k => known.includes(k));
}

Try / catch

try {
  return jwt.sign(payload, secret, options);
} catch (err) {
  if (/is not allowed in/.test(err.message)) {
    const bad = err.message.match(/"([^"]+)" is not allowed/)[1];
    console.warn('Dropping unknown option/claim:', bad);
    const { [bad]: _, ...rest } = options;
    return jwt.sign(payload, secret, rest);
  }
  throw err;
}

Prevention

When it happens

Trigger: jwt.sign(payload, secret, { expireIn: '1h' }) (typo for expiresIn); passing extra options like { headers: {...} } at the wrong nesting level; including a claim in the payload object that collides with an unknown-key rule when payload validation runs with allowUnknown false.

Common situations: Typos in option names (expiresIn, notAfter, subjectcase); migrating from another JWT library with different option names (e.g. 'expires' instead of 'expiresIn'); bulk-passing a config object as options containing unrelated keys.

Related errors

AI-assisted analysis of auth0/node-jsonwebtoken@b924272f29 (2026-09-02). Data as JSON: /api/errors/cdb01c9c915cfec9. Report an issue: GitHub.