{"record":{"id":"e8f693dd8fb616d4","repo":"zitadel/zitadel","slug":"tls-is-enabled-please-specify-a-key-path-and-a","errorCode":null,"errorMessage":"TLS is enabled: please specify a key (path) and a cert (path) or disable TLS if needed (e.g. by setting flag `--tlsMode external` or `--tlsMode disabled","messagePattern":"TLS is enabled: please specify a key \\(path\\) and a cert \\(path\\) or disable TLS if needed \\(e\\.g\\. by setting flag `--tlsMode external` or `--tlsMode disabled","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/config/network/config.go","lineNumber":10,"sourceCode":"package network\n\nimport (\n\t\"crypto/tls\"\n\t\"errors\"\n\t\"os\"\n)\n\nvar (\n\tErrMissingConfig = errors.New(\"TLS is enabled: please specify a key (path) and a cert (path) or disable TLS if needed (e.g. by setting flag `--tlsMode external` or `--tlsMode disabled\")\n)\n\ntype TLS struct {\n\t//If enabled, ZITADEL will serve all traffic over TLS (HTTPS and gRPC)\n\t//you must then also provide a private key and certificate to be used for the connection\n\t//either directly or by a path to the corresponding file\n\tEnabled bool\n\t//Path to the private key of the TLS certificate, it will be loaded into the Key\n\t//and overwrite any exising value\n\tKeyPath string\n\t//Path to the certificate for the TLS connection, it will be loaded into the Cert\n\t//and overwrite any exising value\n\tCertPath string\n\t//Private key of the TLS certificate (KeyPath will this overwrite, if specified)\n\tKey []byte\n\t//Certificate for the TLS connection (CertPath will this overwrite, if specified)\n\tCert []byte\n}","sourceCodeStart":1,"sourceCodeEnd":28,"githubUrl":"https://github.com/zitadel/zitadel/blob/13948f2bcd6f257794dbd6d342c2ac30bc88fe54/internal/config/network/config.go#L1-L28","documentation":"ErrMissingConfig in internal/config/network/config.go is returned when TLS is enabled but the TLS config lacks a server key or certificate. ZITADEL refuses to start serving with incomplete TLS material and instructs the operator to provide key/cert or switch the TLS mode. It is a startup configuration error.","triggerScenarios":"TLS enabled (default tlsMode) while tls.Key or tls.Cert are nil in the compiled Config — i.e. no key/cert given inline and no KeyPath/CertPath resolvable, via Config() at internal/config/network/config.go:47.","commonSituations":"Operator enables TLS but forgets to set the key/cert files in config.yaml or env vars; a path typo makes the file load fail leaving Cert/Key nil; running locally behind a reverse proxy while TLS stays enabled instead of --tlsMode external or disabled.","solutions":["Provide the private key and certificate, either inline in the tls config or via key/cert path options","If a proxy (e.g. nginx/traefik) terminates TLS, start ZITADEL with --tlsMode external","For purely local/dev setups, disable TLS with --tlsMode disabled","Verify configured cert/key paths exist and load successfully so Cert/Key are populated"],"exampleFix":"# before\nTLS:\n  Enabled: true\n# after\nTLS:\n  Enabled: true\n  KeyPath: /etc/zitadel/tls/key.pem\n  CertPath: /etc/zitadel/tls/cert.pem\n# or run with: --tlsMode external (proxy terminates TLS)","handlingStrategy":"validation","validationCode":"if tlsCfg.Enabled && (tlsCfg.Key == nil || tlsCfg.Cert == nil) {\n    return errors.New(\"TLS enabled but key/cert missing: set keyPath/certPath or use --tlsMode external|disabled\")\n}","typeGuard":null,"tryCatchPattern":"// startup config is not catchable at runtime; validate before boot\nif err := validateTLSConfig(cfg.TLS); err != nil {\n    log.Fatalf(\"invalid TLS configuration: %v\", err)\n}","preventionTips":["Match tlsMode to your deployment: disabled for dev, external behind a proxy, enabled only with key+cert provided","Mount cert/key files in containers and verify paths in health/startup checks","Document required TLS env vars in your deployment manifests"],"tags":["go","tls","configuration","startup"],"backgroundTag":"missing-required-config-field","analyzedSha":"13948f2bcd6f257794dbd6d342c2ac30bc88fe54","analyzedAt":"2026-09-06T10:16:19.814Z","contentChangedAt":"2026-09-06T10:16:19.814Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}