{"record":{"id":"72e8fa71d317a931","repo":"hyperledger/fabric","slug":"error-unmarshalling-config-into-struct-s","errorCode":null,"errorMessage":"Error unmarshalling config into struct: %s","messagePattern":"Error unmarshalling config into struct: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"orderer/common/localconfig/config.go","lineNumber":261,"sourceCode":"// Load will load the configuration and cache it on the first call; subsequent\n// calls will return a clone of the configuration that was previously loaded.\nfunc (c *configCache) load() (*TopLevel, error) {\n\tvar uconf TopLevel\n\n\tconfig := viperutil.New()\n\tconfig.SetConfigName(\"orderer\")\n\n\tif err := config.ReadInConfig(); err != nil {\n\t\treturn nil, fmt.Errorf(\"Error reading configuration: %s\", err)\n\t}\n\n\tc.mutex.Lock()\n\tdefer c.mutex.Unlock()\n\tserializedConf, ok := c.cache[config.ConfigFileUsed()]\n\tif !ok {\n\t\terr := config.EnhancedExactUnmarshal(&uconf)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"Error unmarshalling config into struct: %s\", err)\n\t\t}\n\n\t\tserializedConf, err = json.Marshal(uconf)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\n\t\tif c.cache == nil {\n\t\t\tc.cache = map[string][]byte{}\n\t\t}\n\t\tc.cache[config.ConfigFileUsed()] = serializedConf\n\t}\n\n\terr := json.Unmarshal(serializedConf, &uconf)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tuconf.completeInitialization(filepath.Dir(config.ConfigFileUsed()))","sourceCodeStart":243,"sourceCodeEnd":279,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/orderer/common/localconfig/config.go#L243-L279","documentation":"The orderer configuration file was read successfully but could not be unmarshalled into the TopLevel struct via EnhancedExactUnmarshal. EnhancedExact means unknown keys are rejected, so typos or unsupported fields in orderer.yaml cause this error in addition to type mismatches.","triggerScenarios":"config.Load: config.EnhancedExactUnmarshal(&uconf) returns an error because orderer.yaml contains a field with the wrong type (e.g. string where a duration/int is expected) or an unrecognized key not present in the TopLevel schema.","commonSituations":"Upgrading Fabric to a version where config keys were renamed/removed, leaving obsolete keys in orderer.yaml; typos like `Genereal:`; wrong value types (e.g. quoting durations incorrectly); copy-pasting v1.x config into a v2.x/3.x orderer.","solutions":["Read the wrapped error %s — it names the exact offending key/type; fix that field's type or remove it.","Compare orderer.yaml against the sample config for your Fabric version and migrate removed/renamed keys.","Remember unknown keys are rejected (exact unmarshal): delete obsolete or misspelled sections rather than commenting values incorrectly.","Validate with `orderer configtxlator`-free dry run: start the orderer in a test container with the fixed file before redeploying."],"exampleFix":"# before\nGeneral:\n  LedgerType: file\n  ListenPort: \"7050x\"   # wrong type for int\n# after\nGeneral:\n  LedgerType: file\n  ListenPort: 7050","handlingStrategy":"validation","validationCode":"var probe map[string]interface{}\nif err := yaml.Unmarshal(raw, &probe); err != nil { return fmt.Errorf(\"invalid orderer.yaml: %w\", err) }","typeGuard":null,"tryCatchPattern":"if _, err := config.Load(); err != nil && strings.Contains(err.Error(), \"Error unmarshalling config into struct\") { fix the key/type named in the wrapped error }","preventionTips":["Diff orderer.yaml against the sample config when upgrading Fabric versions","Remember EnhancedExact unmarshal rejects unknown keys — remove obsolete fields","Use correct value types (ints unquoted, durations like 5s)","Test config in a staging orderer before production rollout"],"tags":["orderer","fabric","config","yaml-validation"],"backgroundTag":"config-unmarshal-failed","analyzedSha":"2736b63f8fd5932511d56fe68b7039d15977f7f6","analyzedAt":"2026-09-04T08:52:36.465Z","contentChangedAt":"2026-09-04T08:52:36.465Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}