What causes "failed to copy metadataDir directory folder: %s" in hyperledger/fabric?

Correct ledger.state.couchDBConfig.couchDBAddress in core.yaml (host:port)

failed to copy metadataDir directory folder: %s

Error message

failed to copy metadataDir directory folder: %s

What it means

batchRetrieveDocumentMetadata() parses the CouchDB instance URL with url.Parse to build the _all_docs bulk-read URL. If the configured URL is malformed, url.Parse fails and the error is wrapped as 'error parsing CouchDB URL: <url>', aborting the batch document-metadata retrieval used by the ledger during reads/checkpoints.

Source

Thrown at ccaas_builder/cmd/release/main.go:64

	logger.Printf("::Release phase completed")
}

func run() error {
	if len(os.Args) < 3 {
		return errors.New("incorrect number of arguments")
	}

	builderOutputDir, releaseDir := os.Args[1], os.Args[2]
	connectionSrcFile := filepath.Join(builderOutputDir, "/connection.json")

	connectionDir := filepath.Join(releaseDir, "chaincode/server/")
	connectionDestFile := filepath.Join(releaseDir, "chaincode/server/connection.json")

	metadataDir := filepath.Join(builderOutputDir, "META-INF/statedb")
	metadataDestDir := filepath.Join(releaseDir, "statedb")
	if _, err := os.Stat(metadataDir); !os.IsNotExist(err) {
		if err := copy.Copy(metadataDir, metadataDestDir); err != nil {
			return fmt.Errorf("failed to copy metadataDir directory folder: %s", err)
		}
	}

	// Process and update the connections file
	_, err := os.Stat(connectionSrcFile)
	if err != nil {
		return fmt.Errorf("connection.json not found in source folder: %s", err)
	}

	err = os.MkdirAll(connectionDir, 0o750)
	if err != nil {
		return fmt.Errorf("failed to create target folder for connection.json: %s", err)
	}

	if err = Copy(connectionSrcFile, connectionDestFile); err != nil {
		return err
	}

View on GitHub (pinned to 2736b63f8f)

Solutions

Correct ledger.state.couchDBConfig.couchDBAddress in core.yaml (host:port)
Verify env overrides (CORE_LEDGER_STATE_COUCHDBCONFIG_COUCHDBADDRESS) expand properly
Bracket IPv6 literals: [::1]:5984
Test with url.Parse in a snippet using the exact configured string to see the parse error
Recreate the CouchDB instance config and restart the peer

Example fix

// before
couchDBAddress: couchdb.:5984   # invalid host chars
// after
couchDBAddress: couchdb:5984

Defensive patterns

Strategy: validation

Validate before calling

u, err := url.Parse(couchAddress)
if err != nil || u.Host == "" {
    return fmt.Errorf("invalid couchDBAddress %q: %v", couchAddress, err)
}

Try / catch

if err != nil && strings.Contains(err.Error(), "error parsing CouchDB URL") {
    log.Errorf("bad CouchDB address: %v", err) // fix core.yaml and restart
    return err
}

Prevention

Validate couchDBAddress at peer startup, fail fast
Use net.JoinHostPort for host construction (handles IPv6 brackets)
Check env expansion in docker-compose/K8s configs
Avoid manual string concatenation for the CouchDB address
Snapshot working core.yaml and review diffs after changes

When it happens

Trigger: Any batched key lookup against the state database when couchInstance.url() is malformed — same root causes as error 1071: bad couchDBAddress in core.yaml, unresolved env placeholders, stray whitespace or illegal characters in the host string.

Common situations: Misconfigured peer core.yaml, broken docker-compose env substitution for the CouchDB address, IPv6 host without brackets, address copied with a trailing space or scheme included twice (http://http://...).

Related errors

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