{"record":{"id":"0f126ca276aff540","repo":"hyperledger/fabric","slug":"field-s-is-not-valid-for-the-couchdb-state-data","errorCode":null,"errorMessage":"field [%s] is not valid for the CouchDB state database","messagePattern":"field \\[(.+?)\\] is not valid for the CouchDB state database","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/ledger/kvledger/txmgmt/statedb/statecouchdb/couchdoc_conv.go","lineNumber":53,"sourceCode":"type jsonValue map[string]any\n\nfunc tryCastingToJSON(b []byte) (isJSON bool, val jsonValue) {\n\tvar jsonVal map[string]any\n\terr := json.Unmarshal(b, &jsonVal)\n\treturn err == nil, jsonVal\n}\n\nfunc castToJSON(b []byte) (jsonValue, error) {\n\tvar jsonVal map[string]any\n\terr := json.Unmarshal(b, &jsonVal)\n\terr = errors.Wrap(err, \"error unmarshalling json data\")\n\treturn jsonVal, err\n}\n\nfunc (v jsonValue) checkReservedFieldsNotPresent() error {\n\tfor fieldName := range v {\n\t\tif fieldName == versionField || strings.HasPrefix(fieldName, \"_\") {\n\t\t\treturn errors.Errorf(\"field [%s] is not valid for the CouchDB state database\", fieldName)\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc (v jsonValue) removeRevField() {\n\tdelete(v, revField)\n}\n\nfunc (v jsonValue) toBytes() ([]byte, error) {\n\tjsonBytes, err := json.Marshal(v)\n\terr = errors.Wrap(err, \"error marshalling json data\")\n\treturn jsonBytes, err\n}\n\nfunc couchDocToKeyValue(doc *couchDoc) (*keyValue, error) {\n\tdocFields, err := validateAndRetrieveFields(doc)\n\tif err != nil {","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/core/ledger/kvledger/txmgmt/statedb/statecouchdb/couchdoc_conv.go#L35-L71","documentation":"This error is thrown by checkReservedFieldsNotPresent when a JSON value destined for the CouchDB state database contains a field named 'version' or any field whose name begins with an underscore. CouchDB reserves underscore-prefixed fields (e.g. _id, _rev) and Hyperledger Fabric uses 'version' internally, so user-supplied state JSON must never contain them. The check runs before the value is wrapped into a couchDoc.","triggerScenarios":"A chaincode PutState writes a JSON value (via the value-hash or JSON state handling) whose key set includes 'version' or any '_'-prefixed key, and that value passes through jsonValue validation during commit validation.","commonSituations":"Porting application documents that already use CouchDB-style metadata (_id, _rev, _design) or a domain field literally named 'version' (document versioning schemas) directly into chaincode state without renaming the fields.","solutions":["Rename the offending field in the chaincode value, e.g. from 'version' to 'docVersion' or '_rev' to 'rev'","Strip underscore-prefixed metadata fields from the JSON before calling PutState","Add a serialization layer in the chaincode that sanitizes keys before writing state"],"exampleFix":"// before\nvalue := map[string]interface{}{\"version\": \"v1\", \"_rev\": \"1-abc\"}\njsonBytes, _ := json.Marshal(value)\nstub.PutState(key, jsonBytes)\n// after\nvalue := map[string]interface{}{\"docVersion\": \"v1\", \"rev\": \"1-abc\"}\njsonBytes, _ := json.Marshal(value)\nstub.PutState(key, jsonBytes)","handlingStrategy":"validation","validationCode":"func safeForCouchState(v map[string]interface{}) error {\n    for k := range v {\n        if k == \"version\" || strings.HasPrefix(k, \"_\") {\n            return fmt.Errorf(\"field [%s] not allowed in state JSON\", k)\n        }\n    }\n    return nil\n}","typeGuard":"func hasReservedFields(v map[string]interface{}) bool {\n    for k := range v {\n        if k == \"version\" || strings.HasPrefix(k, \"_\") { return true }\n    }\n    return false\n}","tryCatchPattern":null,"preventionTips":["Never use 'version' or '_'-prefixed names in state JSON schemas","Sanitize application documents before writing to ledger state","Keep CouchDB metadata fields out of chaincode value models","Add unit tests asserting key sets of stored documents"],"tags":["couchdb","state-database","fabric-ledger","reserved-fields"],"backgroundTag":"reserved-field-conflict","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"}