Invalid key for this operation, its RSA-PSS parameters do…

Error message

Invalid key for this operation, its RSA-PSS parameters do not meet the requirements of "alg" ${algorithm}.

What it means

RSA-PSS keys embed their hash algorithm, MGF1 hash algorithm, and salt length as key parameters. jsonwebtoken checks that these parameters are consistent with the chosen PS* algorithm (e.g. PS256 requires sha256 hash and sha256 MGF1) and throws when the key's internal parameters don't satisfy the algorithm's requirements.

Solutions

Regenerate the PSS key with matching parameters, e.g. openssl genpkey -algorithm RSA-PSS -pkeyopt rsa_pss_keygen_md:sha256 -pkeyopt rsa_pss_keygen_mgf1_md:sha256 for PS256
Or choose the PS* algorithm matching the key's existing hash (sha384 key -> PS384)
If you cannot regenerate, use a plain RSA (PKCS#1 v1.5) key with RS256 instead

Example fix

// before
openssl genpkey -algorithm RSA-PSS -out key.pem  # defaults may mismatch PS256
// after
openssl genpkey -algorithm RSA-PSS -pkeyopt rsa_pss_keygen_md:sha256 \
  -pkeyopt rsa_pss_keygen_mgf1_md:sha256 -out key.pem

Defensive patterns

Strategy: validation

Validate before calling

function pssHashMatches(alg, key) {
  if (!/^PS/.test(alg)) return true;
  const bits = alg.slice(2);
  const d = key.asymmetricKeyDetails || {};
  return d.hashAlgorithm === 'sha' + bits && d.mgf1HashAlgorithm === d.hashAlgorithm;
}
if (!pssHashMatches(alg, key)) throw new Error('RSA-PSS key hash/mgf1 do not match ' + alg);

Type guard

function isPsCompatibleKey(alg, key) {
  const bits = alg.replace(/^PS/, '');
  const d = key.asymmetricKeyDetails;
  return !d || (d.hashAlgorithm === 'sha' + bits && d.mgf1HashAlgorithm === d.hashAlgorithm);
}

Try / catch

try {
  return jwt.sign(payload, pssKey, { algorithm: alg });
} catch (err) {
  if (/RSA-PSS parameters do not meet/.test(err.message)) {
    throw new Error('Regenerate PSS key with hash+mgf1 = ' + 'sha' + alg.slice(2));
  }
  throw err;
}

Prevention

Generate PSS keys with explicit -pkeyopt rsa_pss_keygen_md and mgf1 md matching the target PS* variant
Keep hash, mgf1 hash, and salt length derived from a single algorithm constant
Inspect key.asymmetricKeyDetails when loading provisioned keys
Prefer RS256 with plain RSA keys unless PSS is a hard requirement

When it happens

Trigger: jwt.sign() or jwt.verify() with an RSA-PSS key whose asymmetricKeyDetails.hashAlgorithm or mgf1HashAlgorithm differs from sha<length> implied by PS256/PS384/PS512 (available on Node >= 12.9 where RSA_PSS_KEY_DETAILS_SUPPORTED is true).

Common situations: Generating a PSS key with openssl using default SHA-1 or SHA-384 parameters then signing with PS256; keys generated for one PSS variant reused for another after an algorithm upgrade; third-party provisioning tools that set mgf1 to a different hash than the key hash.

Related errors

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

Appendix: source

Thrown at lib/validateAsymmetricKey.js:56

  /* istanbul ignore next */
  if (ASYMMETRIC_KEY_DETAILS_SUPPORTED) {
    switch (keyType) {
    case 'ec':
      const keyCurve = key.asymmetricKeyDetails.namedCurve;
      const allowedCurve = allowedCurves[algorithm];

      if (keyCurve !== allowedCurve) {
        throw new Error(`"alg" parameter "${algorithm}" requires curve "${allowedCurve}".`);
      }
      break;

    case 'rsa-pss':
      if (RSA_PSS_KEY_DETAILS_SUPPORTED) {
        const length = parseInt(algorithm.slice(-3), 10);
        const { hashAlgorithm, mgf1HashAlgorithm, saltLength } = key.asymmetricKeyDetails;

        if (hashAlgorithm !== `sha${length}` || mgf1HashAlgorithm !== hashAlgorithm) {
          throw new Error(`Invalid key for this operation, its RSA-PSS parameters do not meet the requirements of "alg" ${algorithm}.`);
        }

        if (saltLength !== undefined && saltLength > length >> 3) {
          throw new Error(`Invalid key for this operation, its RSA-PSS parameter saltLength does not meet the requirements of "alg" ${algorithm}.`)
        }
      }
      break;
    }
  }
}

View on GitHub (pinned to b924272f29)