facebook/docusaurus · error · Error

The certificate key path=${key.path} is invalid.

Error message

The certificate key path=${key.path} is invalid.

What it means

Thrown by `validateKeyAndCerts` when `crypto.createPrivateKey(key.content)` (or the subsequent `createPublicKey`) fails — i.e. the supplied private key is unreadable or in an unsupported format. The original error is attached as `cause`.

Source

Thrown at packages/docusaurus/src/webpack/utils/getHttpsConfig.ts:34

// Works for any key type (RSA, ECDSA, EdDSA, ...) — parses both PEMs and
// checks that the public key embedded in the cert matches the public key
// derived from the private key.
function validateKeyAndCerts({cert, key}: {cert: CryptoFile; key: CryptoFile}) {
  let certPublicKey: crypto.KeyObject;
  try {
    certPublicKey = new crypto.X509Certificate(cert.content).publicKey;
  } catch (error) {
    throw new Error(
      logger.interpolate`The certificate path=${cert.path} is invalid.`,
      {cause: error},
    );
  }

  let keyPublicKey: crypto.KeyObject;
  try {
    keyPublicKey = crypto.createPublicKey(crypto.createPrivateKey(key.content));
  } catch (error) {
    throw new Error(
      logger.interpolate`The certificate key path=${key.path} is invalid.`,
      {cause: error},
    );
  }

  if (!certPublicKey.equals(keyPublicKey)) {
    throw new Error(
      logger.interpolate`The certificate path=${cert.path} and key path=${key.path} do not match.`,
    );
  }
}

type HttpsConfigOptions = {
  https: boolean;
  sslCert: string;
  sslKey: string;
};

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Verify the key parses: `openssl pkey -in key.pem -noout`.
2. If encrypted, decrypt first: `openssl rsa -in encrypted.pem -out plain.pem`.
3. Use a supported PEM private key format; regenerate via `mkcert` if unsure.
4. Ensure you are not pointing `sslKey` at the certificate file.

Example fix

# before (encrypted key, no passphrase support)
docusaurus start --https --ssl-key ./encrypted.key
# after (decrypted PEM key)
docusaurus start --https --ssl-key ./plain.key

const crypto = require('crypto');
const fs = require('fs');
function isValidKey(path: string) {
  try { crypto.createPrivateKey(fs.readFileSync(path)); return true; } catch { return false; }
}

try {
  validateKeyAndCerts({cert, key});
} catch (e) {
  if (/certificate key path=.* is invalid/.test(e.message)) {
    console.error('SSL key unreadable — use a valid unencrypted PEM key');
  }
  throw e;
}

When it happens

Trigger: Passing `--ssl-key` pointing to a file that is not a valid PEM private key (RSA/ECDSA/EdDSA). The try/catch at getHttpsConfig.ts:31-38 wraps the key-parse failure.

Common situations: Key file is encrypted with a passphrase Docusaurus doesn't unlock; wrong format (PKCS#8 vs PKCS#1 vs SEC1); key file is actually the certificate; corruption from copy-paste.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• The certificate path=${cert.path} is invalid.
• The certificate path=${cert.path} and key path=${key.path} d
• You specified ${source}, but file at path path=${filepath} c
• HTTPS support require proving a certificate and key at the s
• You specified ${source}, but file at path path=${filepath} c

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/807bbbe2a9a46735. Report an issue: GitHub.