hyperledger/fabric · error

error parsing CouchDB URL: %s

Error message

error parsing CouchDB URL: %s

What it means

This error is returned by CouchDatabase range query handling when url.Parse fails on the CouchDB instance URL (dbclient.couchInstance.url()). The library parses the instance URL to attach query parameters (limit, include_docs) before issuing the HTTP range request. A malformed URL string makes parsing impossible, so the request is aborted and the underlying net/url error is wrapped with the offending URL text.

Source

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

	couchDoc.attachments = attachments
	return &couchDoc, revision, nil
}

// readDocRange method provides function to a range of documents based on the start and end keys
// startKey and endKey can also be empty strings.  If startKey and endKey are empty, all documents are returned
// This function provides a limit option to specify the max number of entries and is supplied by config.
// Skip is reserved for possible future use.
func (dbclient *couchDatabase) readDocRange(startKey, endKey string, limit int32) ([]*queryResult, string, error) {
	dbName := dbclient.dbName
	couchdbLogger.Debugf("[%s] Entering ReadDocRange()  startKey=%s, endKey=%s", dbName, startKey, endKey)

	var results []*queryResult

	rangeURL, err := url.Parse(dbclient.couchInstance.url())
	if err != nil {
		couchdbLogger.Errorf("URL parse error: %s", err)
		return nil, "", errors.Wrapf(err, "error parsing CouchDB URL: %s", dbclient.couchInstance.url())
	}

	queryParms := rangeURL.Query()
	// Increment the limit by 1 to see if there are more qualifying records
	queryParms.Set("limit", strconv.FormatInt(int64(limit+1), 10))
	queryParms.Add("include_docs", "true")
	queryParms.Add("inclusive_end", "false") // endkey should be exclusive to be consistent with goleveldb
	queryParms.Add("attachments", "true")    // get the attachments as well

	// Append the startKey if provided
	if startKey != "" {
		if startKey, err = encodeForJSON(startKey); err != nil {
			return nil, "", err
		}
		queryParms.Add("startkey", "\""+startKey+"\"")
	}

	// Append the endKey if provided

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Inspect the wrapped message to see the offending URL string and fix the couchDBConfig address in core.yaml (protocol + host + port).
2. Validate the URL with url.Parse (or net.JoinHostPort for IPv6 hosts) before starting the peer.
3. Check environment variable substitutions for stray spaces/newlines in COUCHDB_ADDRESS.
4. Recreate the CouchInstance via CreateCouchInstance so the connection definition is re-parsed after fixing config.

Example fix

// before (core.yaml)
peer:
  ledger:
    state:
      stateDatabase: CouchDB
      couchDBConfig:
        address: http:/couchdb:5984
// after
peer:
  ledger:
    state:
      stateDatabase: CouchDB
      couchDBConfig:
        address: couchdb:5984

if _, err := url.Parse(couchAddr); err != nil {
    return fmt.Errorf("invalid couchDBConfig address %q: %w", couchAddr, err)
}

When it happens

Trigger: Calling RangeScan/ReadRange-related APIs on a CouchDatabase whose couchInstance was constructed with an unparseable URL, e.g. 'error parsing CouchDB URL: http://[::1' or a URL containing spaces/control characters.

Common situations: Ledger config (core.yaml couchDBConfig address) containing stray characters, IPv6 literals without brackets, protocol typos like 'http:/host:5984', or environment-substituted values that inject whitespace or newlines into the address.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• chaincode type not supported: %s
• failed to copy metadataDir directory folder: %s
• error unmarshalling YAML file %s: %s
• number of retries must be zero or greater
• unable to connect to CouchDB, check the hostname and port

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