Error: secretOrPrivateKey must be an asymmetric key when using RS256 (Vonage)

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