{"record":{"id":"9fbfa72b4a4635b8","repo":"temporalio/temporal","slug":"unable-to-load-config-w","errorCode":null,"errorMessage":"unable to load config: %w","messagePattern":"unable to load config: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"temporal/server_options.go","lineNumber":94,"sourceCode":"\t}\n\tfor _, opt := range opts {\n\t\topt.apply(so)\n\t}\n\n\treturn so\n}\n\nfunc (so *serverOptions) loadAndValidate() error {\n\tfor serviceName := range so.serviceNames {\n\t\tif !slices.Contains(Services, string(serviceName)) {\n\t\t\treturn fmt.Errorf(\"invalid service %q in service list %v\", serviceName, so.serviceNames)\n\t\t}\n\t}\n\n\tif so.config == nil {\n\t\terr := so.loadConfig()\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"unable to load config: %w\", err)\n\t\t}\n\t}\n\n\terr := so.validateConfig()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"config validation error: %w\", err)\n\t}\n\n\treturn nil\n}\n\nfunc (so *serverOptions) loadConfig() error {\n\tif so.configFilePath != \"\" {\n\t\tif so.env != \"\" || so.configDir != \"\" || so.zone != \"\" {\n\t\t\treturn errors.New(\"env, config, zone can not be set if configFilePath is set\")\n\t\t}\n\t\tcfg, err := config.Load(\n\t\t\tconfig.WithConfigFile(so.configFilePath),","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/temporal/server_options.go#L76-L112","documentation":"This error is returned by serverOptions.loadAndValidate in the temporal server SDK when loading the server configuration fails (temporal/server_options.go:94). It wraps the underlying error from loadConfig, which itself loads YAML config files via common/config.Load. It is thrown because the server cannot start without a valid, fully-loaded configuration, so it aborts before validation. The wrapped message (typically \"could not load config file: ...\") identifies the actual cause.","triggerScenarios":"Calling temporal.NewServer / temporal.NewServerFgBackgroundService (which calls loadAndValidate) with options where so.config is nil and config.Load fails: e.g. WithConfigFilePath pointing at a nonexistent/malformed YAML file, or WithConfigDir/WithEnv/WithZone resolving to a missing config file, or an env/configDir/zone combined with configFilePath.","commonSituations":"Typo'd or missing config file path, running the server in a container without mounting /etc/temporal/config, using an env name (development/production/docker) whose config directory does not exist, YAML syntax errors, or accidentally setting both ConfigFilePath and Env.","solutions":["Read the wrapped cause after 'unable to load config: ' and fix that root error first (missing file, bad YAML, invalid path).","Verify the file passed to temporal.WithConfigFilePath exists and is valid YAML (temporal server config format with top-level keys like persistence, services, global).","If using WithConfigDir/WithEnv/WithZone, confirm <configDir>/<env>.yaml (or base.yaml + <env>.yaml) exists; default configDir is ./config and default env is 'development'.","Do not set Env/ConfigDir/Zone together with ConfigFilePath — that yields a distinct 'env, config, zone can not be set if configFilePath is set' error wrapped here.","Alternatively pass a fully built config programmatically so config loading is skipped entirely."],"exampleFix":"// before\nserver, err := temporal.NewServer(\n    temporal.WithConfigFilePath(\"/etc/temporal/config.yaml\"), // file does not exist\n)\n// after\nserver, err := temporal.NewServer(\n    temporal.WithConfigFilePath(\"/etc/temporal/config/config_template.yaml\"), // verified path\n)","handlingStrategy":"validation","validationCode":"path := \"/etc/temporal/config/config_template.yaml\"\nif _, err := os.Stat(path); err != nil {\n    return fmt.Errorf(\"config file %s missing before starting server: %w\", path, err)\n}","typeGuard":null,"tryCatchPattern":"server, err := temporal.NewServer(opts...)\nif err != nil {\n    var cfgErr interface{ Unwrap() error }\n    if strings.Contains(err.Error(), \"unable to load config\") {\n        log.Fatalf(\"config load failed: %v\", err) // inspect wrapped cause\n    }\n    return err\n}","preventionTips":["Mount/ship the config directory with your binary and assert its presence at container startup.","Use absolute config file paths in services/containers.","Validate config files in CI (yamllint + temporal server config schema).","Never mix WithConfigFilePath with WithEnv/WithConfigDir/WithZone."],"tags":["go","config","startup","temporal-server"],"backgroundTag":"config-load-failed","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}