hyperledger/fabric · error

failed to unmarshal json [%#v] into dataformatInfo

Error message

failed to unmarshal json [%#v] into dataformatInfo

What it means

decodeDataformatInfo unmarshals the stored dataformatInfo JSON document to determine which data format version the state database uses. If the bytes cannot be unmarshaled, the error is wrapped as 'failed to unmarshal json [%#v] into dataformatInfo' and readDataformatVersion fails, blocking ledger open.

Source

Thrown at core/ledger/kvledger/txmgmt/statedb/statecouchdb/couchdoc_conv.go:271

func encodeDataformatInfo(dataFormatVersion string) (*couchDoc, error) {
	var err error
	dataformatInfo := &dataformatInfo{
		Version: dataFormatVersion,
	}
	dataformatInfoJSON, err := json.Marshal(dataformatInfo)
	if err != nil {
		err = errors.Wrapf(err, "failed to marshal dataformatInfo [%#v]", dataformatInfo)
		logger.Errorf("%+v", err)
		return nil, err
	}
	return &couchDoc{jsonValue: dataformatInfoJSON, attachments: nil}, nil
}

func decodeDataformatInfo(couchDoc *couchDoc) (string, error) {
	dataformatInfo := &dataformatInfo{}
	if err := json.Unmarshal(couchDoc.jsonValue, dataformatInfo); err != nil {
		err = errors.Wrapf(err, "failed to unmarshal json [%#v] into dataformatInfo", couchDoc.jsonValue)
		logger.Errorf("%+v", err)
		return "", err
	}
	return dataformatInfo.Version, nil
}

func validateValue(value []byte) error {
	isJSON, jsonVal := tryCastingToJSON(value)
	if !isJSON {
		return nil
	}
	return jsonVal.checkReservedFieldsNotPresent()
}

func validateKey(key string) error {
	if !utf8.ValidString(key) {
		return errors.Errorf("invalid key [%x], must be a UTF-8 string", key)
	}

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Inspect the dataformat document in CouchDB; fix or restore valid JSON like {"Version":"2.0"}
2. Restore the state database from a good backup taken with the same Fabric version
3. If the database is unrecoverable, drop the database and let the peer rebuild it (data must be re-synced)

Example fix

// before (corrupt doc)
{"Version": {"bad": true}}
// after
{"Version": "2.0"}

func validDataformatJSON(b []byte) bool {
    var d struct{ Version string }
    return json.Unmarshal(b, &d) == nil && d.Version != ""
}

v, err := decodeDataformatInfo(doc)
if err != nil {
    return "", fmt.Errorf("dataformat document corrupt; restore or rebuild state DB: %w", err)
}

When it happens

Trigger: readDataformatVersion reads the dataformatVersion document from CouchDB and its jsonValue cannot be unmarshaled into dataformatInfo (corrupt or wrong-typed fields).

Common situations: Manual edits to the internal dataformat document, partial backups/restores, external tools writing into the ledger database, or version-incompatible databases.

Related errors

• failed to unmarshal savepoint data
• failed to unmarshal channel metadata
• error marshalling json data
• failed to marshal dataformatInfo [%#v]
• too few arguments

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