{"record":{"id":"f70eeac8c89fda3f","repo":"hyperledger/fabric","slug":"unable-to-connect-to-couchdb-check-the-hostname-a","errorCode":null,"errorMessage":"unable to connect to CouchDB, check the hostname and port","messagePattern":"unable to connect to CouchDB, check the hostname and port","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"core/ledger/kvledger/txmgmt/statedb/statecouchdb/couchdb.go","lineNumber":1724,"sourceCode":"\n\t\t\t// backoff, doubling the retry time for next attempt\n\t\t\twaitDuration *= 2\n\n\t\t}\n\n\t} // end retry loop\n\n\t// if a golang http error is still present after retries are exhausted, return the error\n\tif errResp != nil {\n\t\treturn nil, couchDBReturn, errors.Wrap(errResp, \"http error calling couchdb\")\n\t}\n\n\t// This situation should not occur according to the golang spec.\n\t// if this error returned (errResp) from an http call, then the resp should be not nil,\n\t// this is a structure and StatusCode is an int\n\t// This is meant to provide a more graceful error if this should occur\n\tif invalidCouchDBReturn(resp, errResp) {\n\t\treturn nil, nil, errors.New(\"unable to connect to CouchDB, check the hostname and port\")\n\t}\n\n\t// set the return code for the couchDB request\n\tcouchDBReturn.StatusCode = resp.StatusCode\n\n\t// check to see if the status code from couchdb is 400 or higher\n\t// response codes 4XX and 500 will be treated as errors -\n\t// golang error will be created from the couchDBReturn contents and both will be returned\n\tif resp.StatusCode >= http.StatusBadRequest {\n\n\t\t// if the status code is 400 or greater, log and return an error\n\t\tcouchdbLogger.Debugf(\"Error handling CouchDB request. Error:%s,  Status Code:%v,  Reason:%s\",\n\t\t\tcouchDBReturn.Error, resp.StatusCode, couchDBReturn.Reason)\n\n\t\treturn nil, couchDBReturn, errors.Errorf(\"error handling CouchDB request. Error:%s,  Status Code:%v,  Reason:%s\",\n\t\t\tcouchDBReturn.Error, resp.StatusCode, couchDBReturn.Reason)\n\n\t}","sourceCodeStart":1706,"sourceCodeEnd":1742,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/core/ledger/kvledger/txmgmt/statedb/statecouchdb/couchdb.go#L1706-L1742","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the couchdb hostname and port in the peer's core.yaml config","Confirm CouchDB is running and listening (docker ps, curl http://host:5984)","Check DNS/Docker networking between the peer and CouchDB containers","If TLS is enabled, verify certificates and the https scheme match"],"exampleFix":"// before (core.yaml)\naddress: couchdb:5884\n// after\naddress: couchdb:5984","handlingStrategy":"validation","validationCode":"u, err := url.Parse(couchAddress)\nif err != nil || u.Port() == \"\" { return errors.New(\"couchdb address must include host and port\") }\nconn, err := net.DialTimeout(\"tcp\", u.Host, 2*time.Second)\nif err != nil { return fmt.Errorf(\"cannot reach CouchDB at %s\", u.Host) }","typeGuard":null,"tryCatchPattern":"if strings.Contains(err.Error(), \"unable to connect to CouchDB\") {\n    // endpoint unreachable: check hostname/port, container status, DNS\n}","preventionTips":["Verify couchdb hostname resolves inside the peer's network namespace","Expose and publish CouchDB ports correctly in Docker Compose","Run a startup smoke test (GET /) against the configured address"],"tags":["network","connection","couchdb","configuration"],"backgroundTag":"connection-refused","analyzedSha":"2736b63f8fd5932511d56fe68b7039d15977f7f6","analyzedAt":"2026-09-04T08:52:36.465Z","contentChangedAt":"2026-09-04T08:52:36.465Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}