invalid key. Empty string is not supported as a key by couch

Error message

invalid key. Empty string is not supported as a key by couchdb

What it means

validateKey rejects the empty string as a state key because CouchDB does not allow an empty document _id. This check runs whenever a key is validated on write (ValidateKeyValue) or encountered on read (readFromDB).

Source

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

}

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)
	}
	if strings.HasPrefix(key, "_") {
		return errors.Errorf("invalid key [%s], cannot begin with \"_\"", key)
	}
	if key == "" {
		return errors.New("invalid key. Empty string is not supported as a key by couchdb")
	}
	return nil
}

// removeJSONRevision removes the "_rev" if this is a JSON
func removeJSONRevision(jsonValue *[]byte) error {
	jsonVal, err := castToJSON(*jsonValue)
	if err != nil {
		logger.Errorf("Failed to unmarshal couchdb JSON data: %+v", err)
		return err
	}
	jsonVal.removeRevField()
	if *jsonValue, err = jsonVal.toBytes(); err != nil {
		logger.Errorf("Failed to marshal couchdb JSON data: %+v", err)
	}
	return err
}

View on GitHub (pinned to 2736b63f8f)

Solutions

Ensure a non-empty key is supplied before PutState; return a chaincode error to the caller when the key is empty.
Check that all components of a composite key (CreateCompositeKey arguments) are non-empty.
Fix the data source/migration so empty key fields are defaulted or skipped.
For bulk imports, pre-validate records and log/skip entries with empty keys.

Example fix

// before
if key == "" { key = "" } // silent empty key
stub.PutState(key, value)
// after
if key == "" {
  return shim.Error("state key must be non-empty")
}
stub.PutState(key, value)

Defensive patterns

Strategy: validation

Validate before calling

if key == "" {
  return fmt.Errorf("cannot write state key '%s' in ns '%s': empty key", key, ns)
}
stub.PutState(key, value)

Type guard

func isNonEmptyKey(key string) bool { return len(key) > 0 }

Prevention

Validate every composite-key component is non-empty before CreateCompositeKey
Fail fast in chaincode when a lookup variable that feeds the key is missing
Add boundary checks in migration/import tools before writing records

When it happens

Trigger: Calling ValidateKeyValue with key == "", or PutState(ns, "", value) in chaincode; also when readFromDB encounters an empty key in stored data.

Common situations: Chaincode building composite keys where a component variable is empty; deserialization bugs that drop the key field; migration scripts writing rows with empty key columns.

Related errors

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