hyperledger/fabric · error

Error unmarshalling config into struct: %s

Error message

Error unmarshalling config into struct: %s

What it means

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.

Source

Thrown at orderer/common/localconfig/config.go:261

// Load will load the configuration and cache it on the first call; subsequent
// calls will return a clone of the configuration that was previously loaded.
func (c *configCache) load() (*TopLevel, error) {
	var uconf TopLevel

	config := viperutil.New()
	config.SetConfigName("orderer")

	if err := config.ReadInConfig(); err != nil {
		return nil, fmt.Errorf("Error reading configuration: %s", err)
	}

	c.mutex.Lock()
	defer c.mutex.Unlock()
	serializedConf, ok := c.cache[config.ConfigFileUsed()]
	if !ok {
		err := config.EnhancedExactUnmarshal(&uconf)
		if err != nil {
			return nil, fmt.Errorf("Error unmarshalling config into struct: %s", err)
		}

		serializedConf, err = json.Marshal(uconf)
		if err != nil {
			return nil, err
		}

		if c.cache == nil {
			c.cache = map[string][]byte{}
		}
		c.cache[config.ConfigFileUsed()] = serializedConf
	}

	err := json.Unmarshal(serializedConf, &uconf)
	if err != nil {
		return nil, err
	}
	uconf.completeInitialization(filepath.Dir(config.ConfigFileUsed()))

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Read the wrapped error %s — it names the exact offending key/type; fix that field's type or remove it.
2. Compare orderer.yaml against the sample config for your Fabric version and migrate removed/renamed keys.
3. Remember unknown keys are rejected (exact unmarshal): delete obsolete or misspelled sections rather than commenting values incorrectly.
4. Validate with `orderer configtxlator`-free dry run: start the orderer in a test container with the fixed file before redeploying.

Example fix

# before
General:
  LedgerType: file
  ListenPort: "7050x"   # wrong type for int
# after
General:
  LedgerType: file
  ListenPort: 7050

var probe map[string]interface{}
if err := yaml.Unmarshal(raw, &probe); err != nil { return fmt.Errorf("invalid orderer.yaml: %w", err) }

if _, err := config.Load(); err != nil && strings.Contains(err.Error(), "Error unmarshalling config into struct") { fix the key/type named in the wrapped error }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• failed computing orderer addresses
• Error reading configuration: %s
• the block isn't a system channel block because it lacks Cons
• %s is mandatory and cannot be empty
• refusing to generate block which is missing orderer section

AI-assisted analysis of hyperledger/fabric@2736b63f8f (2026-09-04). Data as JSON: /api/errors/72e8fa71d317a931. Report an issue: GitHub.