hyperledger/fabric · critical

http error calling couchdb

Error message

http error calling couchdb

What it means

After all retry attempts are exhausted, if the golang http client itself returned an error (errResp) from the HTTP call — never getting a valid HTTP response — handleRequest wraps it as "http error calling couchdb". It means the peer could not be reached or the request failed at the transport level across every attempt.

Source

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

				couchdbLogger.Warningf("Attempt %d of %d returned Couch DB Error:%s,  Status Code:%v  Reason:%s. %s",
					attempts+1, maxRetries+1, couchDBReturn.Error, resp.Status, couchDBReturn.Reason, retryMessage)

			}
			// if there are more retries remaining, sleep for specified sleep time, then retry
			if attempts < maxRetries {
				time.Sleep(waitDuration)
			}

			// 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 {

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Verify CouchDB is running and reachable (curl the CouchDB URL from the peer host)
2. Check the couchDB address/port and credentials in core.yaml
3. Check network policy/firewall rules and TLS certificate validity
4. Increase maxRetries and retryWaitTime if CouchDB is intermittently unavailable

// preflight connectivity check before opening the ledger
resp, err := http.Get("http://couchdb:5984/_up")
if err != nil { return fmt.Errorf("CouchDB unreachable: %w", err) }

_, _, err := handleRequest(...)
if err != nil && strings.Contains(err.Error(), "http error calling couchdb") {
    // all retries failed at transport level: alert and back off hard
}

When it happens

Trigger: Connection refused/timeout/DNS failure to the CouchDB host on every retry; TLS handshake failure; request context cancelled after retries exhausted.

Common situations: CouchDB container stopped; wrong hostname/port in core.yaml; firewall or network policy blocking the peer-to-CouchDB port; expired TLS certificates.

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

• error reading next multipart
• unable to connect to CouchDB, check the hostname and port
• CouchDB connection error, expecting return code of 200, rece
• failed to create target folder for connection.json: %s
• reading http response body: %s

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