{"record":{"id":"7651027e733ede95","repo":"cocoindex-io/cocoindex","slug":"unexpected-column-subkey-format-sub-key-r-expe","errorCode":null,"errorMessage":"Unexpected column subkey format: {sub_key!r}, expected to start with {_COL_SUBKEY_PREFIX!r}","messagePattern":"Unexpected column subkey format: (.+?), expected to start with (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/bigquery/_target.py","lineNumber":698,"sourceCode":"    _run_query(\n        client,\n        f\"CREATE TABLE{if_not_exists_sql} {qualified_name} ({columns_sql})\",\n    )\n\n\ndef _apply_column_actions(\n    client: Any,\n    key: _TableKey,\n    schema: TableSchema[Any],\n    column_actions: dict[str, statediff.DiffAction],\n) -> None:\n    qualified_name = _qualified_table_name(key.project, key.dataset, key.table_name)\n    pk_cols = set(schema.primary_key)\n    non_pk_col_by_name = {n: c for n, c in schema.columns.items() if n not in pk_cols}\n\n    for sub_key, action in column_actions.items():\n        if not sub_key.startswith(_COL_SUBKEY_PREFIX):\n            raise ValueError(\n                f\"Unexpected column subkey format: {sub_key!r}, expected to start with {_COL_SUBKEY_PREFIX!r}\"\n            )\n        col_name = sub_key[len(_COL_SUBKEY_PREFIX) :]\n        if col_name in pk_cols:\n            continue\n\n        if action == \"delete\":\n            _run_query(\n                client,\n                f\"ALTER TABLE {qualified_name} DROP COLUMN IF EXISTS `{col_name}`\",\n            )\n            continue\n\n        desired_col = non_pk_col_by_name.get(col_name)\n        if desired_col is None:\n            continue\n\n        if action == \"insert\":","sourceCodeStart":680,"sourceCodeEnd":716,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/bigquery/_target.py#L680-L716","documentation":"Raised by _apply_column_actions when a column-level subkey in the action map does not start with the expected internal prefix (_COL_SUBKEY_PREFIX). Subkeys encode column names with a prefix so the connector can distinguish column updates from other child actions; a malformed subkey indicates an internal contract violation.","triggerScenarios":"A target-state key map for a BigQuery table contains a subkey that isn't `col:<name>` format, i.e. produced by a mismatched connector/handler version or hand-constructed action maps.","commonSituations":"Mixed cocoindex versions where target-state state persisted by an older version is replayed by a newer one; custom or monkey-patched target handlers emitting raw column names; corrupted persisted state.","solutions":["Upgrade cocoindex consistently everywhere so persisted target-state subkeys match the current format.","Clear the stale target state (drop/re-sync the BigQuery table state) so subkeys are regenerated.","Do not hand-craft action maps; let the connector derive subkeys."],"exampleFix":"// before\ncolumn_actions = {\"email\": action}\n// after\ncolumn_actions = {\"col:email\": action}  # must use the internal subkey prefix","handlingStrategy":"try-catch","validationCode":"def valid_subkey(k: str) -> bool:\n    return k.startswith(\"col:\")  # matches _COL_SUBKEY_PREFIX\nbad = [k for k in column_actions if not valid_subkey(k)]","typeGuard":"def is_col_subkey(k: str) -> bool:\n    return isinstance(k, str) and k.startswith(\"col:\")","tryCatchPattern":"try:\n    app.update()\nexcept ValueError as e:\n    if \"Unexpected column subkey format\" in str(e):\n        # reset persisted target state and re-sync\n        ...","preventionTips":["Run the same cocoindex version everywhere state is written/read","Never hand-construct target action maps","Clear stale target state after major upgrades"],"tags":["bigquery","internal","schema"],"backgroundTag":"invalid-argument-format","analyzedSha":"e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b","analyzedAt":"2026-09-08T15:59:19.997Z","contentChangedAt":"2026-09-08T15:59:19.997Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}