hyperledger/fabric · critical

CouchDB v%s detected. CouchDB must be at least version 2.0.0

Error message

CouchDB v%s detected. CouchDB must be at least version 2.0.0

What it means

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.

Source

Thrown at core/ledger/kvledger/txmgmt/statedb/statecouchdb/couchdbutil.go:111

	if retVal.StatusCode != http.StatusOK {
		return nil, errors.Errorf("CouchDB connection error, expecting return code of 200, received %v", retVal.StatusCode)
	}

	// check the CouchDB version number, return an error if the version is not at least 2.0.0
	errVersion := checkCouchDBVersion(connectInfo.Version)
	if errVersion != nil {
		return nil, errVersion
	}

	return couchInstance, nil
}

func checkCouchDBVersion(version string) error {
	couchVersion := strings.Split(version, ".")
	majorVersion, _ := strconv.Atoi(couchVersion[0])
	minorVersion, _ := strconv.Atoi(couchVersion[1])
	if majorVersion < 2 {
		return errors.Errorf("CouchDB v%s detected. CouchDB must be at least version 2.0.0", version)
	}
	if majorVersion != 3 || minorVersion < 1 {
		couchdbLogger.Warnf("CouchDB v%s detected. CouchDB versions before 3.1.0 are unsupported.", version)
	}
	return nil
}

// createCouchDatabase creates a CouchDB database object, as well as the underlying database if it does not exist
func createCouchDatabase(couchInstance *couchInstance, dbName string) (*couchDatabase, error) {
	databaseName, err := mapAndValidateDatabaseName(dbName)
	if err != nil {
		couchdbLogger.Errorf("Error calling CouchDB CreateDatabaseIfNotExist() for dbName: %s, error: %s", dbName, err)
		return nil, err
	}

	couchDBDatabase := couchDatabase{couchInstance: couchInstance, dbName: databaseName}

	// Create CouchDB database upon ledger startup, if it doesn't already exist

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Upgrade the CouchDB deployment to 3.1+ (docker pull couchdb:3.1 and migrate data).
2. If you cannot upgrade, disable the CouchDB state database and use LevelDB instead (ledger.state.stateDatabase=goleveldb).
3. Verify the reported version with curl http://host:5984/ to make sure you are hitting the real CouchDB instance, not a different service.

Example fix

// before
docker run couchdb:1.7 ...
// after
docker run -p 5984:5984 -e COUCHDB_USER=admin -e COUCHDB_PASSWORD=adminpass couchdb:3.1

const version = "3.1.0" // reported by GET /
const [major, minor] = version.split(".").map(Number)
if (major < 2) throw new Error("upgrade CouchDB to >= 3.1.0 before starting the peer")

if err != nil {
    if strings.Contains(err.Error(), "must be at least version 2.0.0") {
        // upgrade CouchDB image or fall back to goleveldb
    }
    return err
}

When it happens

Trigger: createCouchInstance connecting to a CouchDB 1.x server (or any server reporting a version string with major < 2) during the version check.

Common situations: 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.

Related errors

• too few arguments
• chaincode type not supported: %s
• incorrect number of arguments
• failed to copy metadataDir directory folder: %s
• connection.json not found in source folder: %s

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