What causes "databaseName '%s' does not match pattern '%s'" in hyperledger/fabric?

Use lowercase alphanumeric channel and chaincode names so the derived database name matches the pattern.

databaseName '%s' does not match pattern '%s'

Error message

databaseName '%s' does not match pattern '%s'

What it means

mapAndValidateDatabaseName matches the provided name against expectedDatabaseNamePattern and requires the whole string to match. If the pattern match length differs from the input length, the name contains characters CouchDB forbids (uppercase, spaces, slashes, etc.) and cannot be safely mapped. Note the library first maps '.' to '$' in callers, so this error means invalid characters remain.

Source

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

// 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 {
	re := regexp.MustCompile(`([A-Z])`)
	dbName = re.ReplaceAllString(dbName, "$$"+"$1")
	return strings.ToLower(dbName)
}

// DropApplicationDBs drops all application databases.
func DropApplicationDBs(config *ledger.CouchDBConfig) error {
	couchdbLogger.Info("Dropping CouchDB application databases ...")

View on GitHub (pinned to 2736b63f8f)

Solutions

Use lowercase alphanumeric channel and chaincode names so the derived database name matches the pattern.
If calling the API directly, sanitize the name first (lowercase, strip disallowed characters, replace '.' with '$').
Check where the name originates (channel ID / namespace) and fix the source identifier.

Example fix

// before
db, err := createCouchDatabase(couchInstance, "My Channel")
// after
name := strings.ToLower(strings.ReplaceAll("My Channel", " ", ""))
db, err := createCouchDatabase(couchInstance, name)

Defensive patterns

Strategy: validation

Validate before calling

const pattern = `^[a-z][a-z0-9-$()_+]*$`
var re = regexp.MustCompile(pattern)
func validDBName(name string) bool { m := re.FindString(name); return len(m) == len(name) }

Try / catch

if err != nil {
    if strings.Contains(err.Error(), "does not match pattern") {
        // lowercase/sanitize the name or fix the channel/chaincode identifier
    }
    return err
}

Prevention

Use only lowercase alphanumerics, '-', '$', '(', ')', '_', '+' in names.
Never create channels with uppercase characters or spaces.
Sanitize names before calling createCouchDatabase directly.

When it happens

Trigger: createCouchDatabase with a databaseName containing characters outside [a-z0-9-$()_+] or starting with a non-letter, e.g. channel names with uppercase letters, underscores at the start, or spaces.

Common situations: Channels or chaincode names created with uppercase characters (Fabric normally rejects these upstream); external code calling the CouchDB layer directly with un-sanitized names; database names from legacy data that violate the newer pattern.

Related errors

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