CouchDB connection error, expecting return code of 200, rece

Error message

CouchDB connection error, expecting return code of 200, received %v

What it means

createCouchInstance verifies the CouchDB connection with an initial HTTP request; if the response status is not exactly 200 OK, it returns this error. It means the peer reached an HTTP server at the configured address but that server did not behave like a healthy CouchDB 2.x+ instance (or rejected the request).

Source

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

		DisableKeepAlives:     disableKeepAlive,
	}

	client.Transport = transport

	// Create the CouchDB instance
	couchInstance := &couchInstance{
		conf:   config,
		client: client,
		stats:  newStats(metricsProvider),
	}
	connectInfo, retVal, verifyErr := couchInstance.verifyCouchConfig()
	if verifyErr != nil {
		return nil, verifyErr
	}

	// return an error if the http return value is not 200
	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)
	}

View on GitHub (pinned to 2736b63f8f)

Solutions

Verify CouchDB address, port, username and password in the peer configuration (CORE_LEDGER_STATE_COUCHDBCONFIG_* env vars or core.yaml).
Confirm the server actually responds 200: curl -X GET http://admin:password@host:5984/ — it must return CouchDB JSON (db_name, version).
Check that no proxy/firewall intercepts the request and returns another status.
Ensure CouchDB is running and fully started (systemctl status / docker logs).

Example fix

// before (misconfigured)
CORE_LEDGER_STATE_COUCHDBCONFIG_USERNAME=wronguser
// after
CORE_LEDGER_STATE_COUCHDBCONFIG_COUCHDBADDRESS=host:5984
CORE_LEDGER_STATE_COUCHDBCONFIG_USERNAME=admin
CORE_LEDGER_STATE_COUCHDBCONFIG_PASSWORD=adminpass

Defensive patterns

Strategy: validation

Validate before calling

const (
  addr  = "localhost:5984"
  user  = "admin"
  pass  = "adminpass"
)
resp, _ := http.Get("http://" + user + ":" + pass + "@" + addr + "/")
// must return 200 with JSON body containing "couchdb"

Try / catch

couchInstance, err := couchdb.CreateCouchInstance(connectInfo, ...)
if err != nil {
    if strings.Contains(err.Error(), "expecting return code of 200") {
        // check credentials, address, and that CouchDB (not a proxy) answers
    }
    return err
}

Prevention

Smoke-test GET / on the CouchDB URL with curl before peer startup.
Point the config at CouchDB itself, not a proxy or another service.
Confirm CouchDB is fully started before launching the peer.
Keep credentials in env/config consistent with the CouchDB admin setup.

When it happens

Trigger: Calling CreateCouchInstance with connectInfo whose probe request (e.g. GET / with credentials) returns anything other than 200 — 401 unauthorized, 404 wrong path/proxy, 503 unavailable, or a non-CouchDB HTTP server answering.

Common situations: Wrong username/password in config; a reverse proxy or another service listening on the CouchDB port; CouchDB behind authentication that rejects the credentials; misconfigured port (e.g. pointing to the peer or another web service).

Related errors

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