gatsbyjs/gatsby · error

11522

11522

Error message

Failed to generate dev SSL certificate

What it means

Thrown when Gatsby's automatic dev-SSL path fails. After confirming no custom cert/key were provided, getSslCert delegates to `@expo/devcert`'s `certificateFor` to generate and trust a local CA. If that call rejects (permission error, missing certutil, Windows keychain access denied, corrupted devcert config dir, HOME not writable), the catch block panics with the underlying error's message.

Source

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

      process.env.HOME = mkdtemp
    }
    const getDevCert = require(`@expo/devcert`).certificateFor
    const { caPath, key, cert } = await getDevCert(name, {
      getCaPath: true,
      skipCertutilInstall: false,
      ui: {
        getWindowsEncryptionPassword,
      },
    })
    if (caPath) {
      process.env.NODE_EXTRA_CA_CERTS = caPath
    }
    return {
      key: key.toString(),
      cert: cert.toString(),
    }
  } catch (err) {
    report.panic({
      id: `11522`,
      error: err,
      context: {
        message: err.message,
      },
    })
  }

  return false
}

View on GitHub (pinned to 8b06340921)

Solutions

  1. Install the system cert tooling devcert needs: `sudo apt-get install libnss3-tools` (Linux) or ensure `certutil` is on PATH.
  2. Provide your own pre-generated cert to bypass automatic generation: `gatsby develop --https --cert-file cert.pem --key-file key.pem`.
  3. Remove the corrupted devcert state dir (e.g. `rm -rf ~/.config/devcert ~/.cache/devcert`) and retry so devcert re-initializes its CA.
  4. Run with sufficient privileges or in an interactive shell so the trust prompt can complete; in CI prefer a committed custom cert.
  5. Ensure HOME is set and writable (`echo $HOME`) before launching.

Example fix

// before
gatsby develop --https
// after (skip auto-generation with a committed cert)
gatsby develop --https --cert-file ./cert.pem --key-file ./key.pem
Defensive patterns

Strategy: fallback

Validate before calling

// Preflight checks before relying on automatic devcert generation.
const os = require('os')
const fs = require('fs')
function devcertPreflight() {
  const problems = []
  if (['linux','darwin'].includes(os.platform()) && (!process.env.HOME || !fs.existsSync(process.env.HOME))) {
    problems.push('HOME is unset or missing; devcert cannot initialize its config dir.')
  }
  if (os.platform() === 'linux') {
    try { require('child_process').execSync('command -v certutil', { stdio: 'ignore' }) }
    catch { problems.push('certutil not found; install libnss3-tools for devcert trust.') }
  }
  return problems
}

Try / catch

// Fall back to a provided custom cert when auto-generation is unavailable.
try {
  cert = await getSslCert({ name, directory })
} catch (e) {
  if (process.env.GATSBY_CERT_FILE && process.env.GATSBY_KEY_FILE) {
    cert = await getSslCert({ name, directory, certFile: process.env.GATSBY_CERT_FILE, keyFile: process.env.GATSBY_KEY_FILE })
  } else { throw e }
}

Prevention

When it happens

Trigger: Running `gatsby develop --https` (no custom cert/key) on an environment where @expo/devcert cannot install its CA, cannot write to its config directory, or cannot elevate privileges. Also triggered when process.env.HOME had to be faked to a tmpdir that devcert then cannot use persistently.

Common situations: First-time HTTPS setup on Linux without `libnss3`/`certutil` installed; running inside a container as a non-root user without write access to the devcert config path; macOS Keychain or Windows credential prompt denied/cancelled; CI runners where no sudo/interactive elevation is possible; corrupted `~/.config/devcert` or `~/.cache/devcert`.

Understand the failure class

Related errors

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