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

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.

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)

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.