hyperledger/fabric · error

database name is illegal, cannot be empty

Error message

database name is illegal, cannot be empty

What it means

mapAndValidateDatabaseName rejects an empty database name string before applying mapping rules. CouchDB database names must be non-empty; the statecouchdb layer validates length and character constraints up-front. This error means the caller passed a zero-length name.

Source

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

		return chainName + "_" + escapedNamespace + "(" + hashOfNamespaceDBName + ")"
	}
	return namespaceDBName
}

// 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
}

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Ensure the channel name / ledger ID used to derive the database name is set and non-empty before opening the ledger.
2. Check the peer configuration for an empty ledger or chaincode identifier.
3. Trace the caller (createCouchDatabase) to see where the empty string originates and fix the name derivation.

Example fix

// before
if namespace == "" { db, _ := createCouchDatabase(couchInstance, namespace) }
// after
if namespace == "" { return errors.New("namespace must be non-empty") }
db, err := createCouchDatabase(couchInstance, namespace)

func validateDBName(name string) error {
    if name == "" { return errors.New("database name must not be empty") }
    return nil
}

if err != nil {
    if strings.Contains(err.Error(), "cannot be empty") {
        // the channel/ledger id used to derive the name was empty; fix the source
    }
    return err
}

When it happens

Trigger: createCouchDatabase (and tests) invoked with a databaseName of "", typically from an empty channel name or empty namespace-derived name passed to CreateCouchDatabase/CreateSystemDatabase.

Common situations: Misconfigured channel or ledger ID; a caller constructing database names from an unset variable; bug in namespace-to-databasename mapping producing empty output.

Related errors

• database name is illegal, cannot be longer than %d
• 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/d173146d96d1bb27. Report an issue: GitHub.