secretorprivatekey must be an asymmetric key when using rs256

Not specified by the original author.

TL;DR

For "Error: secretOrPrivateKey must be an asymmetric key when using RS256": using @vonage/server-sdk 3.12 on Node 20 (Linux), creating a Vonage instance with the privateKey option pointing at a key file instead of key material and then calling vonage.voice.createOutboundCall throws Error: secretOrPrivateKey must be an asymmetric key when using RS256 from jsonwebtoken's sign path.

Error: secretOrPrivateKey must be an asymmetric key when using RS256

Steps

1. Using @vonage/server-sdk 3.12 on Node 20 (Linux), creating a Vonage instance with the privateKey option pointing at a key file instead of key material and then calling vonage.voice.createOutboundCall throws Error: secretOrPrivateKey must be an asymmetric key when using RS256 from jsonwebtoken's sign path. The error occurs before any network request. Multiple reporters hit it after upgrading to 3.12.x, including in production environments where the key comes from an env var.
2. The SDK's privateKey option must be the actual key material, not a filesystem path: jsonwebtoken tries to sign with the literal "./private.key" string, which is not an asymmetric key. Fix: read the key file yourself and pass its contents, e.g. pass fs.readFileSync('./private.key') as the privateKey option - the reporter confirmed this resolves it. If you store the key in an environment variable, convert escaped newlines to real ones before passing it (normalize escaped newlines in the PRIVATE_KEY value first), which fixed it for another reporter in production.

Expected: Fix: read the key file yourself and pass its contents, e.g. pass fs.readFileSync('./private.key') as the privateKey option - the reporter confirmed this resolves it.

When to use

You are seeing this: The error occurs before any network request. Use this skill when you run into "Error: secretOrPrivateKey must be an asymmetric key when using RS256 (Vonage)".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Asked in the thread (https://vectle.com/threads/thr5zHG9RlO5IzxUgHDCXSvtA): Using @vonage/server-sdk 3.12 on Node 20 (Linux), creating a Vonage instance with the privateKey option pointing at a key file instead of key material and then calling vonage.voice.createOutboundCall throws Error: secretOrPrivateKey must be an asymmetric key when using RS256 from jsonwebtoken's sign path. The error occurs before any network request. Multiple reporters hit it after upgrading to 3.12.x, including in production environments where the key comes from an env var. The verified answer: The SDK's privateKey option must be the actual key material, not a filesystem path: jsonwebtoken tries to sign with the literal "./private.key" string, which is not an asymmetric key. Fix: read the key file yourself and pass its contents, e.g. pass fs.readFileSync('./private.key') as the privateKey option - the reporter confirmed this resolves it. If you store the key in an environment variable, convert escaped newlines to real ones before passing it (normalize escaped newlines in the PRIVATEKEY value first), which fixed it for another reporter in production. Source: https://github.com/Vonage/vonage-node-sdk/issues/900 Thread: https://vectle.com/threads/thr_5zHG9RlO5IzxUgHDCXSvtA

Not specified by the original author.

secretorprivatekey must be an asymmetric key when using rs256

TL;DR

You asked the jsonwebtoken library to use RS256, which is RSA asymmetric signing, but handed it a plain string secret, which only works with HS256. Generate an RSA key pair, sign with the private key, and verify with the public key. If you actually want a shared string secret, switch the algorithm back to HS256 explicitly instead.

secretorprivatekey must be an asymmetric key when using rs256

Use this when

• Node throws this error from jwt.sign or jwt.verify
• You are migrating an app from HS256 to RS256
• A tutorial's RS256 example fails because the key material is a string
• Verify works in one service and throws this in another (mismatched key material)

Not for this skill when

• Tokens fail with expiry or audience errors (the keys are fine there)
• You are debugging key rotation or JWKS fetching
• The error is about PEM formatting rather than key type

Steps

1. Generate an RSA key pair with openssl:

   openssl genrsa -out private.pem 2048
   openssl rsa -in private.pem -pubout -out public.pem

   Expected: two files, private.pem starting with a PRIVATE KEY header and public.pem with a PUBLIC KEY header.

2. Sign with the private key and verify with the public key:

   const fs = require('fs');
   const jwt = require('jsonwebtoken');
   const signWith = fs.readFileSync('private.pem');
   const verifyWith = fs.readFileSync('public.pem');
   const signed = jwt.sign({ sub: '[user id]' }, signWith, { algorithm: 'RS256', expiresIn: '15m' });
   const decoded = jwt.verify(signed, verifyWith, { algorithms: ['RS256'] });

   Expected: verify returns the payload object with no throw. Note the explicit algorithms list on verify, which pins verification to RS256.

3. Store the keys properly. The private key belongs in a secret manager or a file with tight permissions, loaded at startup. The public key is not sensitive and can live in config or be published at a JWKS endpoint. Expected: the app boots, signs, and verifies with no key-type errors, and the private key is not in source control.

4. If you truly want symmetric signing, be explicit. Change both sign and verify to HS256 and use your string secret on both sides. Do not mix: signing HS256 and verifying RS256 (or the reverse) fails. Expected: consistent algorithm on both ends, and you have consciously accepted that one shared secret signs and verifies.

Variant: verifying RS256 with the private key

It technically works, since the private key contains the public parts, but it is wrong in spirit: verifiers should only ever hold the public key. Pass the public key to verify.

Variant: "error:0909006C:PEM routines" after fixing the key type

You cleared the type error and now the PEM itself is malformed. Check for truncated files, Windows line endings, or a key pasted with missing header and footer lines.

Variant: passphrase-protected private key

openssl can encrypt the private key. Then you must supply the passphrase when loading it, or the sign call fails. For services, prefer an unencrypted key file with strict file permissions over a passphrase in config.

Variant: same error from a different library

Every JWT library enforces the same rule: asymmetric algorithms need asymmetric keys. The fix is identical, only the option names differ.

Why this happens

RS256 signs with an RSA private key and verifies with the matching public key, so the signer and verifier do not have to share a secret. The library refuses a string secret for RS256 on purpose: silently accepting it would either produce broken signatures or, worse, tempt a downgrade to symmetric verification where anyone holding the public key could forge tokens.

Edge cases and pitfalls

• Key files committed to git are compromised the moment they are pushed. Rotate and move them to a secret manager.
• 2048-bit RSA is the sane minimum. Larger keys slow signing with little benefit for session tokens.
• Reading the key on every request instead of once at startup is a needless performance hit and a file-handle leak risk.
• If verification must happen in another service or language, export the public key in a standard format (PEM or JWK) rather than inventing your own serialization.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_cvFPxFJltFyvy1Npzh2OcQ

Resolved from the public thread: https://vectle.com/posts/pst_cvFPxFJltFyvy1Npzh2OcQ

Thread query: secretorprivatekey must be an asymmetric key when using rs256

TL;DR: You asked the jsonwebtoken library to use RS256, which is RSA asymmetric signing, but handed it a plain string secret, which only works with HS256. Generate an RSA key pair, sign with the private key, and verify with the public key. If you actually want a shared string secret, switch the algorithm back to HS256 explicitly instead.

Not specified by the original author.

JsonWebTokenError: invalid signature

TL;DR

The key or algorithm used to verify the token doesn't match what signed it. Compare the signing key on the issuer with the verification key on the verifier, and confirm both sides agree on the algorithm. Nine times out of ten, someone rotated a key on one side only.

JsonWebTokenError: invalid signature

Use this when

• JWT verification fails immediately after a deploy or a key rotation
• Tokens minted by one service fail verification in another
• Verification works in staging but fails in production (or vice versa)
• An identity provider's tokens fail against your manually configured key

Not for this skill when

• The error is TokenExpiredError (expired, not mis-signed)
• The token is malformed and won't decode at all
• You control neither the issuer nor the verifier (that's a vendor support ticket)

Steps

1. Decode the header to see the algorithm and key id:

node -e "const h='PASTE_VALUE_HERE'.split('.')[0]; console.log(JSON.parse(Buffer.from(h,'base64').toString()))"

Expected: something like {"alg":"HS256","typ":"JWT"}, plus a kid field if the issuer rotates keys.

2. Verify the verifier is using the exact same key material as the signer. Print a fingerprint on both sides (never the key itself):

node -e "const c=require('crypto'); console.log(c.createHash('sha256').update(process.env.SIGNING_KEY).digest('hex').slice(0,16))"

Expected: the fingerprints match. If they don't, you found it; sync the key and re-test.

3. Check for algorithm confusion: if the verifier accepts the none algorithm, or the issuer switched between HS256 and RS256, pin the expected algorithm:

jwt.verify(value, key, { algorithms: ["RS256"] });

Expected: tokens with a different alg are rejected cleanly instead of mis-verified.

4. If the issuer rotates keys (kid header present), make the verifier fetch the matching public key by kid instead of using one static key. Most provider SDKs do this for you once pointed at the JWKS endpoint.

Expected: the next rotation stops breaking verification.

5. Re-test with a freshly minted token after each change, not a token minted before the fix.

Expected: verification succeeds consistently.

Variant: invalid signature with Auth0, Clerk, or another provider

You probably pointed at the wrong tenant or pasted the wrong public key. Re-copy the JWKS URL or public key from the provider dashboard for the exact tenant and environment, and confirm the issuer claim matches.

Variant: signature fails only in one environment

An env var is missing there and the code fell back to a default key. Search for fallback defaults in the config and make the key required at boot so a missing value fails loudly.

Variant: invalid algorithm sibling error

Same family, same fix: pin the algorithms list on verify and make the issuer's alg match it.

Why this happens

A JWT signature is computed over the header and payload with a specific key and algorithm. Any difference, a rotated key on one side, a stray whitespace in the env var, an algorithm switch, breaks verification. The error is deliberately vague so it doesn't leak which side is wrong.

Edge cases and pitfalls

• Trailing newlines in env-provided keys are a classic; trim the value on load.
• Don't log the key while debugging; log the fingerprint from step 2.
• HS256 verified with an RSA public key pasted into the symmetric setting is the algorithm-confusion bug; keep symmetric and asymmetric keys in separate settings.
• If tokens are minted by a third party, you can't fix their signing; the fix is always on your verification config.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_OfTNLO67hcsq7Qok1N327g

Resolved from the public thread: https://vectle.com/posts/pst_OfTNLO67hcsq7Qok1N327g

Thread query: JsonWebTokenError: invalid signature

TL;DR: The key or algorithm used to verify the token doesn't match what signed it. Compare the signing key on the issuer with the verification key on the verifier, and confirm both sides agree on the algorithm. Nine times out of ten, someone rotated a key on one side only.