What causes "error unmarshalling YAML file %s: %s" in hyperledger/fabric?

Fix ledger.state.couchDBConfig.couchDBAddress to a valid host:port

error unmarshalling YAML file %s: %s

Error message

error unmarshalling YAML file %s: %s

What it means

batchUpdateDocuments() parses the CouchDB instance URL with url.Parse to build the _bulk_docs URL. If the configured URL is malformed, url.Parse fails and the error is wrapped as 'error parsing CouchDB URL: <url>'; the entire batch write of documents is aborted before any HTTP request is sent.

Source

Thrown at cmd/common/config.go:34

)

// Config aggregates configuration of TLS and signing
type Config struct {
	Version      int
	TLSConfig    comm.Config
	SignerConfig signer.Config
}

// ConfigFromFile loads the given file and converts it to a Config
func ConfigFromFile(file string) (Config, error) {
	configData, err := os.ReadFile(file)
	if err != nil {
		return Config{}, errors.WithStack(err)
	}
	config := Config{}

	if err := yaml.Unmarshal(configData, &config); err != nil {
		return Config{}, errors.Errorf("error unmarshalling YAML file %s: %s", file, err)
	}

	return config, validateConfig(config)
}

// ToFile writes the config into a file
func (c Config) ToFile(file string) error {
	if err := validateConfig(c); err != nil {
		return errors.Wrap(err, "config isn't valid")
	}
	b, err := yaml.Marshal(c)
	if err != nil {
		return errors.Wrap(err, "failed to marshal config")
	}
	if err := os.WriteFile(file, b, 0o600); err != nil {
		return errors.Errorf("failed writing file %s: %v", file, err)
	}
	return nil

View on GitHub (pinned to 2736b63f8f)

Solutions

Fix ledger.state.couchDBConfig.couchDBAddress to a valid host:port
Resolve CORE_LEDGER_STATE_COUCHDBCONFIG_COUCHDBADDRESS env overrides correctly
Bracket IPv6 literals: [::1]:5984
Print dbclient.couchInstance.url() and validate with url.Parse to see the exact parse failure
Validate peer core.yaml (and any config overlays) after edits before restarting

Example fix

// before
couchDBAddress: couchdb: 5984   # space breaks parsing
// after
couchDBAddress: couchdb:5984

Defensive patterns

Strategy: validation

Validate before calling

u, err := url.Parse(couchAddress)
if err != nil || u.Host == "" {
    return fmt.Errorf("invalid couchDBAddress %q: %v", couchAddress, err)
}

Try / catch

if err != nil && strings.Contains(err.Error(), "error parsing CouchDB URL") {
    return fmt.Errorf("peer couchDBAddress invalid, no docs written: %w", err)
}

Prevention

Validate the address at startup so writes never reach a broken config
Use bare host:port; never include scheme or whitespace
Bracket IPv6 literals explicitly
Automate config linting in CI for core.yaml changes
Confirm env substitutions resolve in every deployment environment

When it happens

Trigger: A batched write (from state commits or checkpoints) where couchInstance.url() is malformed — bad couchDBAddress in core.yaml, unresolved env placeholders, illegal characters/whitespace in the host portion.

Common situations: Peer config mistakes (typo, trailing space, missing host), broken env substitution in containerized deployments, IPv6 address without brackets after a config edit.

Related errors

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