{"record":{"id":"b49e4f65b609b4e7","repo":"cocoindex-io/cocoindex","slug":"unexpected-column-subkey-format-sub-key-r-expe-b49e4f","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":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/connectors/postgres/_target.py","lineNumber":1125,"sourceCode":"        self,\n        conn: asyncpg.pool.PoolConnectionProxy[asyncpg.Record],\n        key: _TableKey,\n        schema: TableSchema[Any],\n        column_actions: dict[str, statediff.DiffAction],\n    ) -> None:\n        qualified_name = _qualified_table_name(key.table_name, key.pg_schema_name)\n        pk_cols = set(schema.primary_key)\n        non_pk_col_by_name = {\n            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 sub_key == _EXT_PGVECTOR_SUBKEY:\n                if action != \"delete\":\n                    await self._ensure_pgvector_extension(conn)\n                continue\n\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\n            # Defensive: we never ALTER PK columns here.\n            if col_name in pk_cols:\n                continue\n\n            if action == \"delete\":\n                await conn.execute(\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                # If the desired schema no longer mentions this column, treat\n                # it as a no-op here; \"delete\" should have been emitted.","sourceCodeStart":1107,"sourceCodeEnd":1143,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/connectors/postgres/_target.py#L1107-L1143","documentation":"Raised in `_apply_column_actions` when a state subkey encountered during column sync does not start with the expected `_COL_SUBKEY_PREFIX`. This is an internal format check on the target-state keys stored between runs; column subkeys must be prefixed so column actions can be distinguished from other subkey kinds (like the pgvector extension subkey).","triggerScenarios":"A stale or corrupted state entry for the table target whose subkey isn't a recognized column subkey — typically after upgrading the library when the internal subkey scheme changed, or manual tampering with stored state.","commonSituations":"Upgrading cocoindex across versions that changed internal state key formats and then syncing a previously-created table; copying state between environments; mixing connector versions in a cluster.","solutions":["Upgrade the library cleanly and re-create/re-sync the table target (drop the stale target state) so subkeys are rewritten in the current format.","Clear the stored component/target state for this component path and run a full update.","If reproducible on the latest version, file a bug with the offending subkey value from the message."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"# check library version consistency across the environment\nimport cocoindex, importlib.metadata as im\nassert im.version(\"cocoindex\") == cocoindex.__version__","typeGuard":null,"tryCatchPattern":"try:\n    await app.update()\nexcept ValueError as e:\n    if \"Unexpected column subkey format\" in str(e):\n        logger.error(\"Stale target state after upgrade; recreate table target\")\n    else:\n        raise","preventionTips":["Upgrade cocoindex atomically across all services that share state.","Recreate target states after major version upgrades.","Never hand-edit stored engine state."],"tags":["postgres","internal-state","subkey-format"],"backgroundTag":"internal-invariant-violation","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"}