cocoindex-io/cocoindex · error · ValueError

Invalid Neo4j database name: {database!r}. Must match [A-Za-

Error message

Invalid Neo4j database name: {database!r}. Must match [A-Za-z0-9._-]+.

What it means

This ValueError is raised by the Neo4j target connector's __init__ when the database name contains characters outside [A-Za-z0-9._-]. The connector deliberately rejects characters that would require escaping in Cypher or connection settings, rather than escaping them. Neo4j 5 database identifiers may contain hyphens and dots, which the regex allows.

Source

Thrown at python/cocoindex/connectors/neo4j/_target.py:150

            uri="bolt://localhost:7687",
            auth=("neo4j", "cocoindex"),
            database="neo4j",
        )
        builder.provide(NEO4J_DB, factory)
    """

    def __init__(
        self,
        uri: str,
        *,
        auth: tuple[str, str] | None = None,
        database: str = "neo4j",
    ) -> None:
        # Database identifiers in Neo4j 5 may contain hyphens and dots; be
        # less strict than the Cypher identifier validator. Just reject the
        # obviously dangerous characters so we don't have to escape.
        if not re.match(r"^[A-Za-z0-9._-]+$", database):
            raise ValueError(
                f"Invalid Neo4j database name: {database!r}. "
                "Must match [A-Za-z0-9._-]+."
            )
        self._uri = uri
        self._auth = auth
        self._database = database

    @property
    def database(self) -> str:
        return self._database

    async def acquire(self) -> _GraphHandle:
        """Return a graph handle ready to issue ``query(cypher, params)``."""
        driver = _neo4j.AsyncGraphDatabase.driver(self._uri, auth=self._auth)
        return _GraphHandle(driver, self._database)


# ---------------------------------------------------------------------------

View on GitHub (pinned to e84aa99b32)

Solutions

1. Pass a plain database identifier matching [A-Za-z0-9._-]+, e.g. "neo4j" or "my-db.v2".
2. Strip/sanitize the source value: re.sub(r'[^A-Za-z0-9._-]', '_', name) or .strip() before constructing.
3. Confirm you are passing the database name, not a URI or file path.

Example fix

// before
Neo4jTarget(uri=uri, auth=auth, database="my database/one")
// after
Neo4jTarget(uri=uri, auth=auth, database="my_database_one")

import re
assert re.match(r"^[A-Za-z0-9._-]+$", database), f"bad database name: {database!r}"

try:
    target = Neo4jTarget(uri=uri, auth=auth, database=database)
except ValueError as e:
    database = re.sub(r"[^A-Za-z0-9._-]", "_", database.strip())
    target = Neo4jTarget(uri=uri, auth=auth, database=database)

When it happens

Trigger: Constructing the Neo4j target with database containing whitespace, slashes, quotes, or other special characters — e.g. database="my db", database="db/2024", or an interpolated name built from a URL segment or environment variable with stray characters.

Common situations: Passing a full DSN or connection string fragment as the database name; an env var with trailing whitespace or newline; building the name from user input without sanitization; confusing database name with URI path.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Invalid BigQuery {kind}: {name!r}
• Invalid identifier: {name}
• Invalid FalkorDB {kind}: {name!r}. Must match [a-zA-Z_][a-zA
• Invalid Neo4j {kind}: {name!r}. Must match [a-zA-Z_][a-zA-Z0
• build_relationship_index_create requires at least one field

AI-assisted analysis of cocoindex-io/cocoindex@e84aa99b32 (2026-09-08). Data as JSON: /api/errors/ad7b8a78cd5bc1c2. Report an issue: GitHub.