11521

11521

Error message

for custom ssl --https, --cert-file, and --key-file must be used together

What it means

Thrown by getSslCert when starting the dev server with HTTPS using custom certificates. Gatsby requires that --cert-file and --key-file be supplied together (both or neither); supplying only one is treated as a misconfiguration. The guard is the XOR-like check `certFile ? !keyFile : keyFile`, which panics when exactly one of the two is set. When neither is set, Gatsby falls back to automatic SSL via @expo/devcert.

Source

Thrown at packages/gatsby/src/utils/get-ssl-cert.ts:55

export interface IGetSslCertArgs {
  name: string
  certFile?: string
  keyFile?: string
  caFile?: string
  directory: string
}

export async function getSslCert({
  name,
  certFile,
  keyFile,
  caFile,
  directory,
}: IGetSslCertArgs): Promise<ICert | false> {
  // check that cert file and key file are both true or both false, if they are both
  // false, it defaults to the automatic ssl
  if (certFile ? !keyFile : keyFile) {
    report.panic({
      id: `11521`,
      context: {},
    })
  }

  if (certFile && keyFile) {
    const keyPath = absoluteOrDirectory(directory, keyFile)
    const certPath = absoluteOrDirectory(directory, certFile)

    process.env.NODE_EXTRA_CA_CERTS = caFile
      ? absoluteOrDirectory(directory, caFile)
      : certPath
    return {
      key: fs.readFileSync(keyPath, `utf-8`),
      cert: fs.readFileSync(certPath, `utf-8`),
    }
  }

View on GitHub (pinned to 8b06340921)

Solutions

Supply both flags together: `gatsby develop --https --cert-file ./cert.pem --key-file ./key.pem`.
If you want Gatsby to generate a cert automatically, remove BOTH --cert-file and --key-file and keep only --https.
Double-check shell quoting/expansion so an empty variable like `$KEY_FILE` does not silently drop one of the flags.

Example fix

// before
gatsby develop --https --cert-file ./cert.pem
// after
gatsby develop --https --cert-file ./cert.pem --key-file ./key.pem

Defensive patterns

Strategy: validation

Validate before calling

// Validate cert/key flags before calling getSslCert or running the CLI.
function validateSslFlags({ https, certFile, keyFile }) {
  if (!https) return null
  const hasCert = Boolean(certFile)
  const hasKey = Boolean(keyFile)
  if (hasCert !== hasKey) {
    return 'When using --https with a custom cert, pass BOTH --cert-file and --key-file (or neither for auto SSL).'
  }
  return null
}

Type guard

function isCompleteCustomSslArgs(args) {
  const c = Boolean(args?.certFile)
  const k = Boolean(args?.keyFile)
  return (c && k) || (!c && !k)
}

Prevention

Treat --cert-file and --key-file as a single coupled option in scripts and docs.
In programmatic wrappers, assert `Boolean(certFile) === Boolean(keyFile)` before calling getSslCert.
Add a preflight CLI flag parser test that fails if exactly one is set.

When it happens

Trigger: Invoking `gatsby develop --https` with `--cert-file` but not `--key-file`, or vice versa. Equivalently, passing `{ certFile }` or `{ keyFile }` alone to getSslCert programmatically without the matching key/cert argument.

Common situations: Copying a partial curl/openssl example that only mentions one flag; forgetting the key after pointing at a `.pem`/`.crt`; CI scripts that template only one of the two paths; switching from an automatic cert to a custom one and forgetting the second flag.

Understand the failure class

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

Related errors

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/a3a7548f9161ab1c. Report an issue: GitHub.