facebook/docusaurus · error · Error

You specified ${source}, but file at path path=${filepath} c

Error message

You specified ${source}, but file at path path=${filepath} can't be found.

What it means

Thrown by readCryptoFile() in the HTTPS dev-server config when Docusaurus resolves an SSL cert/key file path (from --ssl-cert/--ssl-key CLI args, or DOCUSAURUS_SSL_CRT_FILE/DOCUSAURUS_SSL_KEY_FILE/SSL_CRT_FILE/SSL_KEY_FILE env vars) but fs.pathExists reports the file does not exist. The {source} placeholder names exactly which input supplied the path so you know which knob to fix. The path is resolved relative to process.cwd() (via fs.realpath), so relative paths are interpreted from the directory you ran the CLI in.

Source

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

      : undefined) ??
    (typeof process.env.HTTPS !== 'undefined'
      ? process.env.HTTPS == 'true'
      : undefined)
  );
}

type CryptoFile = {
  path: string;
  content: Buffer;
  source: string;
};

async function readCryptoFile(
  filepath: string,
  source: string,
): Promise<CryptoFile> {
  if (!(await fs.pathExists(filepath))) {
    throw new Error(
      logger.interpolate`You specified ${source}, but file at path path=${filepath} can't be found.`,
    );
  }
  try {
    return {
      path: filepath,
      source,
      content: await fs.readFile(filepath),
    };
  } catch (error) {
    throw new Error(
      logger.interpolate`You specified ${source}, but file at path path=${filepath} can't be read.`,
      {cause: error},
    );
  }
}

function getCert(

View on GitHub (pinned to 3f483e80e3)

Solutions

Verify the file exists at the resolved absolute path: `ls -la "$(pwd)/<your-cert-path>"` and compare it to the path in the error message.
If using a relative path, remember it is resolved from process.cwd() — run the CLI from the directory the path is relative to, or switch to an absolute path.
Generate a local cert/key pair first, e.g. `mkcert localhost` then point --ssl-cert ./localhost.pem --ssl-key ./localhost-key.pem.
Check the {source} label in the message to confirm whether the path came from a CLI flag or an env var, and fix that specific input (unset the stale env var if you meant to use the CLI flag).

Example fix

// before
DOCUSAURUS_SSL_CRT_FILE=certs/server.crt docusaurus start --https
// after (path resolved from cwd; use absolute if unsure)
DOCUSAURUS_SSL_CRT_FILE=/abs/path/to/certs/server.crt docusaurus start --https

Defensive patterns

Strategy: validation

Validate before calling

import fs from 'fs-extra';
import path from 'path';

async function assertCryptoFileExists(rawPath: string, cwd = process.cwd()) {
  const abs = path.resolve(cwd, rawPath);
  if (!(await fs.pathExists(abs))) {
    throw new Error(`SSL file not found (resolved to ${abs}). Generate one with: mkcert localhost`);
  }
  return abs;
}

// before starting: await assertCryptoFileExists(process.env.DOCUSAURUS_SSL_CRT_FILE);

Type guard

const isNonEmptyString = (v: unknown): v is string =>
  typeof v === 'string' && v.trim().length > 0;

Prevention

Always pass SSL cert/key paths as absolute paths to avoid cwd-dependent resolution.
Keep cert/key generation in the project setup script (mkcert) so every contributor has them.
Document the required env vars (DOCUSAURUS_SSL_CRT_FILE / DOCUSAURUS_SSL_KEY_FILE) in the repo README.

When it happens

Trigger: Running `docusaurus start --https --ssl-cert ./cert.pem --ssl-key ./key.pem` (or setting DOCUSAURUS_SSL_CRT_FILE / SSL_CRT_FILE / DOCUSAURUS_SSL_KEY_FILE / SSL_KEY_FILE) where the referenced file does not exist on disk. Also triggered when the path has a typo, points to an absolute location that is only valid in another environment, or when cwd differs from where the certs actually live.

Common situations: Following an HTTPS tutorial that assumes certs live in the project root, but they were generated elsewhere; checking the repo out on a new machine where mkcert certs were never created; using a relative path while running the CLI from a different working directory than expected; trailing whitespace or quote mistakes in the env var value.

Related errors

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