{"record":{"id":"a3a7548f9161ab1c","repo":"gatsbyjs/gatsby","slug":"11521","errorCode":"11521","errorMessage":"for custom ssl --https, --cert-file, and --key-file must be used together","messagePattern":"for custom ssl --https, --cert-file, and --key-file must be used together","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/gatsby/src/utils/get-ssl-cert.ts","lineNumber":55,"sourceCode":"export interface IGetSslCertArgs {\n  name: string\n  certFile?: string\n  keyFile?: string\n  caFile?: string\n  directory: string\n}\n\nexport async function getSslCert({\n  name,\n  certFile,\n  keyFile,\n  caFile,\n  directory,\n}: IGetSslCertArgs): Promise<ICert | false> {\n  // check that cert file and key file are both true or both false, if they are both\n  // false, it defaults to the automatic ssl\n  if (certFile ? !keyFile : keyFile) {\n    report.panic({\n      id: `11521`,\n      context: {},\n    })\n  }\n\n  if (certFile && keyFile) {\n    const keyPath = absoluteOrDirectory(directory, keyFile)\n    const certPath = absoluteOrDirectory(directory, certFile)\n\n    process.env.NODE_EXTRA_CA_CERTS = caFile\n      ? absoluteOrDirectory(directory, caFile)\n      : certPath\n    return {\n      key: fs.readFileSync(keyPath, `utf-8`),\n      cert: fs.readFileSync(certPath, `utf-8`),\n    }\n  }\n","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby/src/utils/get-ssl-cert.ts#L37-L73","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\ngatsby develop --https --cert-file ./cert.pem\n// after\ngatsby develop --https --cert-file ./cert.pem --key-file ./key.pem","handlingStrategy":"validation","validationCode":"// Validate cert/key flags before calling getSslCert or running the CLI.\nfunction validateSslFlags({ https, certFile, keyFile }) {\n  if (!https) return null\n  const hasCert = Boolean(certFile)\n  const hasKey = Boolean(keyFile)\n  if (hasCert !== hasKey) {\n    return 'When using --https with a custom cert, pass BOTH --cert-file and --key-file (or neither for auto SSL).'\n  }\n  return null\n}","typeGuard":"function isCompleteCustomSslArgs(args) {\n  const c = Boolean(args?.certFile)\n  const k = Boolean(args?.keyFile)\n  return (c && k) || (!c && !k)\n}","tryCatchPattern":null,"preventionTips":["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."],"tags":["ssl","https","dev-server","configuration","cli-flags"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}