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.

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

• CouchDB connection error, expecting return code of 200…
• http error calling couchdb
• chaincode address not provided
• chaincode type not supported
• connection to terminated

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

Appendix: 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)