hyperledger/fabric · error

database name is illegal, cannot be longer than %d

Error message

database name is illegal, cannot be longer than %d

What it means

mapAndValidateDatabaseName enforces a maximum database name length (maxLength). CouchDB itself limits database names, so the library rejects names longer than this limit before mapping. This error fires when the provided name exceeds maxLength bytes.

Source

Thrown at core/ledger/kvledger/txmgmt/statedb/statecouchdb/couchdbutil.go:284

}

// mapAndValidateDatabaseName checks to see if the database name contains illegal characters
// CouchDB Rules: Only lowercase characters (a-z), digits (0-9), and any of the characters
// _, $, (, ), +, -, and / are allowed. Must begin with a letter.
//
// Restrictions have already been applied to the database name from Orderer based on
// restrictions required by Kafka and couchDB (except a '.' char). The databaseName
// passed in here is expected to follow `[a-z][a-z0-9.$_()+-]*` pattern.
//
// This validation will simply check whether the database name matches the above pattern and will replace
// all occurrence of '.' by '$'. This will not cause collisions in the transformed named
func mapAndValidateDatabaseName(databaseName string) (string, error) {
	// test Length
	if len(databaseName) <= 0 {
		return "", errors.Errorf("database name is illegal, cannot be empty")
	}
	if len(databaseName) > maxLength {
		return "", errors.Errorf("database name is illegal, cannot be longer than %d", maxLength)
	}
	re, err := regexp.Compile(expectedDatabaseNamePattern)
	if err != nil {
		return "", errors.Wrapf(err, "error compiling regexp: %s", expectedDatabaseNamePattern)
	}
	matched := re.FindString(databaseName)
	if len(matched) != len(databaseName) {
		return "", errors.Errorf("databaseName '%s' does not match pattern '%s'", databaseName, expectedDatabaseNamePattern)
	}
	// replace all '.' to '$'. The databaseName passed in will never contain an '$'.
	// So, this translation will not cause collisions
	databaseName = strings.Replace(databaseName, ".", "$", -1)
	return databaseName, nil
}

// escapeUpperCase replaces every upper case letter with a '$' and the respective
// lower-case letter
func escapeUpperCase(dbName string) string {

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Shorten the channel name or chaincode name so the derived database name fits within maxLength.
2. Check maxLength in couchdbutil.go and keep identifiers well under the limit when designing names.
3. If the name cannot change, use LevelDB as the state database, which has no such name restriction.

Example fix

// before: name too long
channelName := "averyveryverylongchannelnameexceedinglimits..."
// after: keep identifiers short
channelName := "mychannel"

const maxLength = 249 // as in couchdbutil.go
if len(dbName) > maxLength { /* shorten channel/chaincode name before opening ledger */ }

if err != nil {
    if strings.Contains(err.Error(), "cannot be longer than") {
        // shorten identifiers or switch to goleveldb state database
    }
    return err
}

When it happens

Trigger: createCouchDatabase invoked with a databaseName whose length exceeds maxLength — typically a very long chaincode name or channel name producing an oversized namespace-derived database name.

Common situations: Chaincode instantiated with an extremely long name; channel IDs at/near the maximum combined with long chaincode names; earlier Fabric versions allowed longer names and data was migrated.

Related errors

• database name is illegal, cannot be empty
• databaseName '%s' does not match pattern '%s'
• JSON format is not valid
• number of retries must be zero or greater
• error creating http request

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