gatsbyjs/gatsby · error

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

Error message

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

What it means

Thrown by `gatsby develop` when the user supplies --cert-file or --key-file without also passing --https. Custom SSL requires all three flags together; omitting --https while giving a cert/key is treated as a misconfiguration and the command panics before starting the dev server.

Source

Thrown at packages/gatsby/src/commands/develop.ts:198

    throw e
  }

  // Run the actual develop server on a random port, and the proxy on the program port
  // which users will access
  const debugInfo = getDebugInfo(program)

  const rootFile = (file: string): string => path.join(program.directory, file)

  // Require gatsby-config.js before accessing process.env, to enable the user to change
  // environment variables from the config file.
  requireUncached(rootFile(`gatsby-config`))

  const developPort = program.port

  // In order to enable custom ssl, --cert-file --key-file and -https flags must all be
  // used together
  if ((program[`cert-file`] || program[`key-file`]) && !program.https) {
    reporter.panic(
      `for custom ssl --https, --cert-file, and --key-file must be used together`
    )
  }

  // Check if https is enabled, then create or get SSL cert.
  // Certs are named 'devcert' and issued to the host.
  // NOTE(@mxstbr): We mutate program.ssl _after_ passing it
  // to the develop process controllable script above because
  // that would mean we double SSL browser => proxy => server
  if (program.https) {
    const sslHost =
      program.host === `0.0.0.0` || program.host === `::`
        ? `localhost`
        : program.host

    if (REGEX_IP.test(sslHost)) {
      reporter.panic(
        `You're trying to generate a ssl certificate for an IP (${sslHost}). Please use a hostname instead.`

View on GitHub (pinned to 8b06340921)

Solutions

1. Pass all three flags together: `gatsby develop --https --cert-file ./cert.pem --key-file ./key.pem`.
2. If you do not want HTTPS, remove --cert-file and --key-file entirely.
3. Update npm scripts that build the flag list to include --https whenever cert/key are set.

Example fix

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

// Build the develop argv safely before spawning gatsby
const wantsCert = Boolean(argv.certFile || argv.keyFile)
const finalArgs = [...baseArgs]
if (wantsCert) finalArgs.push('--https', '--cert-file', argv.certFile, '--key-file', argv.keyFile)

When it happens

Trigger: CLI invocation includes `--cert-file <path>` or `--key-file <path>` but `program.https` is falsy (the --https flag was not passed).

Common situations: Copying a partial SSL invocation from docs; assuming --cert-file implies HTTPS; scripts that pass cert/key conditionally but forget to also pass https.

Understand the failure class

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

Related errors

• You're trying to generate a ssl certificate for an IP (${ssl
• 11521
• 11522
• MissingInfoError
• Did not recognize ${curr}

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