chroma-core/chroma · error · ValueError

Database name must be at least 3 characters long

Error message

Database name must be at least 3 characters long

What it means

SegmentAPI.create_database (chromadb/api/segment.py:155) validates that a database name has at least 3 characters before creating it. Shorter names raise ValueError before any quota check or sysdb write happens, so nothing is persisted.

Source

Thrown at chromadb/api/segment.py:161

        self._settings = system.settings
        self._sysdb = self.require(SysDB)
        self._manager = self.require(SegmentManager)
        self._executor = self.require(Executor)
        self._quota_enforcer = self.require(QuotaEnforcer)
        self._product_telemetry_client = self.require(ProductTelemetryClient)
        self._opentelemetry_client = self.require(OpenTelemetryClient)
        self._producer = self.require(Producer)
        self._rate_limit_enforcer = self._system.require(RateLimitEnforcer)

    @override
    def heartbeat(self) -> int:
        return int(time.time_ns())

    @trace_method("SegmentAPI.create_database", OpenTelemetryGranularity.OPERATION)
    @override
    def create_database(self, name: str, tenant: str = DEFAULT_TENANT) -> None:
        if len(name) < 3:
            raise ValueError("Database name must be at least 3 characters long")

        self._quota_enforcer.enforce(
            action=Action.CREATE_DATABASE,
            tenant=tenant,
            name=name,
        )

        self._sysdb.create_database(
            id=uuid4(),
            name=name,
            tenant=tenant,
        )

    @trace_method("SegmentAPI.get_database", OpenTelemetryGranularity.OPERATION)
    @override
    def get_database(self, name: str, tenant: str = DEFAULT_TENANT) -> t.Database:
        return self._sysdb.get_database(name=name, tenant=tenant)

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Use a name of 3+ characters: 'db' -> 'dev-db'
2. Default/fallback to a valid name when the source variable may be empty or short
3. Validate tenant/database names at config load time, not at call time

Example fix

# before
client.create_database(name=os.environ.get('DB_NAME', ''))  # ValueError if short/empty

# after
db_name = os.environ.get('DB_NAME') or 'default-db'
assert len(db_name) >= 3
client.create_database(name=db_name)

def validate_resource_name(name: str, minimum: int = 3) -> str:
    name = (name or '').strip()
    if len(name) < minimum:
        raise ValueError(f'name must be at least {minimum} characters: {name!r}')
    return name

# db = validate_resource_name(os.environ.get('DB_NAME', ''))

def is_valid_db_name(name: str) -> bool:
    return isinstance(name, str) and len(name.strip()) >= 3

try:
    client.create_database(name=db_name)
except ValueError as e:
    if 'at least 3 characters' in str(e):
        client.create_database(name=f'db-{db_name}')
    else:
        raise

When it happens

Trigger: client.create_database('db') or create_database('a') - any name with len < 3, including empty string ''.

Common situations: Creating per-environment databases with terse names ('dv', 'qa', 'p'); passing an empty or truncated variable (e.g. os.environ.get('DB_NAME', '')) straight into create_database; test fixtures with 1-2 char names.

Related errors

• Expected collection name that (1) contains 3-63 characters,
• Tenant name must be at least 3 characters long
• MinK keys cannot be empty
• MaxK keys cannot be empty
• GroupBy keys cannot be empty

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/dbc9ffebdfcbc4d6. Report an issue: GitHub.