hyperledger/fabric · critical

unable to connect to CouchDB, check the hostname and port

Error message

unable to connect to CouchDB, check the hostname and port

What it means

A graceful fallback in handleRequest: if after the HTTP call the response is invalid (resp is nil while errResp indicates a failure, per invalidCouchDBReturn), handleRequest returns this error instead of dereferencing a nil response. It almost always means the configured CouchDB endpoint was unreachable.

Source

Thrown at core/ledger/kvledger/txmgmt/statedb/statecouchdb/couchdb.go:1724

			// backoff, doubling the retry time for next attempt
			waitDuration *= 2

		}

	} // end retry loop

	// if a golang http error is still present after retries are exhausted, return the error
	if errResp != nil {
		return nil, couchDBReturn, errors.Wrap(errResp, "http error calling couchdb")
	}

	// This situation should not occur according to the golang spec.
	// if this error returned (errResp) from an http call, then the resp should be not nil,
	// this is a structure and StatusCode is an int
	// This is meant to provide a more graceful error if this should occur
	if invalidCouchDBReturn(resp, errResp) {
		return nil, nil, errors.New("unable to connect to CouchDB, check the hostname and port")
	}

	// set the return code for the couchDB request
	couchDBReturn.StatusCode = resp.StatusCode

	// check to see if the status code from couchdb is 400 or higher
	// response codes 4XX and 500 will be treated as errors -
	// golang error will be created from the couchDBReturn contents and both will be returned
	if resp.StatusCode >= http.StatusBadRequest {

		// if the status code is 400 or greater, log and return an error
		couchdbLogger.Debugf("Error handling CouchDB request. Error:%s,  Status Code:%v,  Reason:%s",
			couchDBReturn.Error, resp.StatusCode, couchDBReturn.Reason)

		return nil, couchDBReturn, errors.Errorf("error handling CouchDB request. Error:%s,  Status Code:%v,  Reason:%s",
			couchDBReturn.Error, resp.StatusCode, couchDBReturn.Reason)

	}

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Verify the couchdb hostname and port in the peer's core.yaml config
2. Confirm CouchDB is running and listening (docker ps, curl http://host:5984)
3. Check DNS/Docker networking between the peer and CouchDB containers
4. If TLS is enabled, verify certificates and the https scheme match

Example fix

// before (core.yaml)
address: couchdb:5884
// after
address: couchdb:5984

u, err := url.Parse(couchAddress)
if err != nil || u.Port() == "" { return errors.New("couchdb address must include host and port") }
conn, err := net.DialTimeout("tcp", u.Host, 2*time.Second)
if err != nil { return fmt.Errorf("cannot reach CouchDB at %s", u.Host) }

if strings.Contains(err.Error(), "unable to connect to CouchDB") {
    // endpoint unreachable: check hostname/port, container status, DNS
}

When it happens

Trigger: Every attempt to call CouchDB fails at the transport level so resp stays nil: wrong hostname/port, CouchDB not listening, DNS resolution failure, or TLS errors.

Common situations: Docker network misconfiguration (peer cannot resolve 'couchdb' hostname); CouchDB port not exposed from the container; stale IP in peer config; CouchDB service crashed at startup.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• http error calling couchdb
• CouchDB connection error, expecting return code of 200, rece
• chaincode type not supported: %s
• failed to copy metadataDir directory folder: %s
• failed to create target folder for connection.json: %s

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