cocoindex-io/cocoindex · error

Invalid BigQuery {kind}: {name!r}

Error message

Invalid BigQuery {kind}: {name!r}

What it means

_validate_identifier checks that BigQuery dataset and table identifiers are strings matching _IDENTIFIER_RE (BigQuery's legal identifier charset). Invalid characters, backticks, dots inside an identifier, or non-string values raise this ValueError with the offending name and kind.

Source

Thrown at python/cocoindex/connectors/bigquery/_target.py:243

                annotation.encoder,
                annotation.use_parse_json,
            )

    base_type = type_info.base_type
    if base_type in _LEAF_TYPE_MAPPINGS:
        return _LEAF_TYPE_MAPPINGS[base_type]

    if isinstance(
        type_info.variant, (SequenceType, MappingType, RecordType, UnionType, AnyType)
    ):
        return _JSON_MAPPING

    return _JSON_MAPPING


def _validate_identifier(name: str, kind: str = "identifier") -> None:
    if not isinstance(name, str) or not _IDENTIFIER_RE.match(name):
        raise ValueError(f"Invalid BigQuery {kind}: {name!r}")


def _validate_project_id(project: str) -> None:
    if not isinstance(project, str) or not _PROJECT_RE.match(project):
        raise ValueError(f"Invalid BigQuery project: {project!r}")


def _quote_path(parts: Sequence[str]) -> str:
    return f"`{'.'.join(parts)}`"


def _qualified_table_name(project: str | None, dataset: str, table_name: str) -> str:
    parts = []
    if project is not None:
        _validate_project_id(project)
        parts.append(project)
    _validate_identifier(dataset)
    _validate_identifier(table_name)

View on GitHub (pinned to e84aa99b32)

Solutions

1. Use only letters, numbers, and underscores, starting with a letter or underscore, for dataset/table names.
2. Replace hyphens with underscores: 'my-dataset' -> 'my_dataset'.
3. Sanitize/validate dynamically built names before calling table_target (re.match your own allowlist).
4. Ensure the full qualified name is split into project/dataset/table before validation; don't pass 'proj.ds.tbl' as the dataset part.

Example fix

// before
target = table_target(client, "my-proj.my-dataset.my table", Row, primary_key=["id"])

// after
target = table_target(client, "my_proj.my_dataset.my_table", Row, primary_key=["id"])

import re
IDENT = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
assert IDENT.fullmatch(dataset) and IDENT.fullmatch(table), "invalid BigQuery identifier"

def valid_bq_identifier(name: object) -> bool:
    import re
    return isinstance(name, str) and bool(re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", name))

try:
    target = table_target(client, f"{project}.{dataset}.{table}", Row, primary_key=pk)
except ValueError as e:
    logger.error("invalid identifier: %s", e)
    raise

When it happens

Trigger: Calling table_target(client, 'proj.dataset.table', ...) with a dataset/table containing illegal characters (spaces, dashes, dots, backticks) or a non-str (None, int) — via any of the callers _qualified_table_name, _qualified_dataset_name, or table_target.

Common situations: Interpolating env vars or user input into table names; using hyphenated names (dashes are illegal in BigQuery identifiers); passing parts that still contain dots from a prior split mistake.

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 project: {project!r}
• expected None{loc}, got {type(value).__name__}
• expected {tp}{loc}, got {type(value).__name__}: {value!r}
• expected tuple{loc}, got {type(value).__name__}
• expected {tp}{loc}, got {type(value).__name__}

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