gatsbyjs/gatsby · error

You're trying to generate a ssl certificate for an IP (${ssl

Error message

You're trying to generate a ssl certificate for an IP (${sslHost}). Please use a hostname instead.

What it means

Thrown by `gatsby develop` when --https is set and the resolved host (after normalizing 0.0.0.0/:: to localhost) matches an IP address (REGEX_IP). devcert cannot issue a trusted certificate for a bare IP, so the command panics asking the user to use a hostname instead.

Source

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

  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.`
      )
    }

    const ssl = await getSslCert({
      name: sslHost,
      caFile: program[`ca-file`],
      certFile: program[`cert-file`],
      keyFile: program[`key-file`],
      directory: program.directory,
    })

    if (ssl) {
      program.ssl = ssl
    }
  }

  const developProcess = new ControllableScript(

View on GitHub (pinned to 8b06340921)

Solutions

1. Use a hostname instead of an IP: `--https -H mymachine.local` or a DNS-resolvable name.
2. Add a hosts entry (e.g. 127.0.0.1 mymachine.local) and pass that hostname.
3. If you must serve over an IP, terminate TLS upstream with a valid cert and run Gatsby over plain HTTP behind the proxy.

Example fix

// before
gatsby develop --https -H 192.168.1.10
// after
gatsby develop --https -H mymachine.local

// Reject IP hosts before launching gatsby develop with HTTPS
const REGEX_IP = /^(\d{1,3}\.){3}\d{1,3}$|^[0-9a-fA-F:]+$/
if (argv.https && REGEX_IP.test(argv.host)) {
  throw new Error('Use a hostname, not an IP, for HTTPS dev certs')
}

When it happens

Trigger: program.https is true and sslHost (program.host, or 'localhost' when host is 0.0.0.0/::) matches REGEX_IP, e.g. `--https -H 192.168.1.10`.

Common situations: Pointing the dev server at a LAN IP for testing on another device; passing a docker host IP; using tailscale/full IP-only addressing.

Understand the failure class

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

Related errors

• for custom ssl --https, --cert-file, and --key-file must be
• 11522
• 11521
• Something went wrong when trying to add the plugins to the p
• starter ${starterPath} doesn't exist

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