{"record":{"id":"c5abf7af7d26d81e","repo":"hyperledger/fabric","slug":"couchdb-v-s-detected-couchdb-must-be-at-least-ver","errorCode":null,"errorMessage":"CouchDB v%s detected. CouchDB must be at least version 2.0.0","messagePattern":"CouchDB v(.+?) detected\\. CouchDB must be at least version 2\\.0\\.0","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"core/ledger/kvledger/txmgmt/statedb/statecouchdb/couchdbutil.go","lineNumber":111,"sourceCode":"\tif retVal.StatusCode != http.StatusOK {\n\t\treturn nil, errors.Errorf(\"CouchDB connection error, expecting return code of 200, received %v\", retVal.StatusCode)\n\t}\n\n\t// check the CouchDB version number, return an error if the version is not at least 2.0.0\n\terrVersion := checkCouchDBVersion(connectInfo.Version)\n\tif errVersion != nil {\n\t\treturn nil, errVersion\n\t}\n\n\treturn couchInstance, nil\n}\n\nfunc checkCouchDBVersion(version string) error {\n\tcouchVersion := strings.Split(version, \".\")\n\tmajorVersion, _ := strconv.Atoi(couchVersion[0])\n\tminorVersion, _ := strconv.Atoi(couchVersion[1])\n\tif majorVersion < 2 {\n\t\treturn errors.Errorf(\"CouchDB v%s detected. CouchDB must be at least version 2.0.0\", version)\n\t}\n\tif majorVersion != 3 || minorVersion < 1 {\n\t\tcouchdbLogger.Warnf(\"CouchDB v%s detected. CouchDB versions before 3.1.0 are unsupported.\", version)\n\t}\n\treturn nil\n}\n\n// createCouchDatabase creates a CouchDB database object, as well as the underlying database if it does not exist\nfunc createCouchDatabase(couchInstance *couchInstance, dbName string) (*couchDatabase, error) {\n\tdatabaseName, err := mapAndValidateDatabaseName(dbName)\n\tif err != nil {\n\t\tcouchdbLogger.Errorf(\"Error calling CouchDB CreateDatabaseIfNotExist() for dbName: %s, error: %s\", dbName, err)\n\t\treturn nil, err\n\t}\n\n\tcouchDBDatabase := couchDatabase{couchInstance: couchInstance, dbName: databaseName}\n\n\t// Create CouchDB database upon ledger startup, if it doesn't already exist","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/core/ledger/kvledger/txmgmt/statedb/statecouchdb/couchdbutil.go#L93-L129","documentation":"checkCouchDBVersion parses the CouchDB version string from the server's welcome response and returns this error when the major version is below 2. The library requires CouchDB 2.0.0 or newer because earlier versions lack the APIs and behavior the state database depends on. Versions before 3.1.0 additionally trigger a warning but are allowed.","triggerScenarios":"createCouchInstance connecting to a CouchDB 1.x server (or any server reporting a version string with major < 2) during the version check.","commonSituations":"Docker image pinning an old couchdb:1.x tag; connecting to a non-CouchDB service whose / reports a version like 1.x; hardened/managed CouchDB deployments stuck on legacy versions.","solutions":["Upgrade the CouchDB deployment to 3.1+ (docker pull couchdb:3.1 and migrate data).","If you cannot upgrade, disable the CouchDB state database and use LevelDB instead (ledger.state.stateDatabase=goleveldb).","Verify the reported version with curl http://host:5984/ to make sure you are hitting the real CouchDB instance, not a different service."],"exampleFix":"// before\ndocker run couchdb:1.7 ...\n// after\ndocker run -p 5984:5984 -e COUCHDB_USER=admin -e COUCHDB_PASSWORD=adminpass couchdb:3.1","handlingStrategy":"validation","validationCode":"const version = \"3.1.0\" // reported by GET /\nconst [major, minor] = version.split(\".\").map(Number)\nif (major < 2) throw new Error(\"upgrade CouchDB to >= 3.1.0 before starting the peer\")","typeGuard":null,"tryCatchPattern":"if err != nil {\n    if strings.Contains(err.Error(), \"must be at least version 2.0.0\") {\n        // upgrade CouchDB image or fall back to goleveldb\n    }\n    return err\n}","preventionTips":["Pin CouchDB docker images to couchdb:3.1 or newer.","Check GET / version output during deployment health checks.","Plan migrations when upgrading old 1.x deployments.","Keep peer and CouchDB versions within supported combinations."],"tags":["couchdb","version","compatibility"],"backgroundTag":"unsupported-version","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"}