{"record":{"id":"5e38ab165a2fa323","repo":"RyanCodrai/turbovec","slug":"turboquantvectordb-not-initialized-call-create","errorCode":null,"errorMessage":"TurboQuantVectorDb not initialized — call create() before insert().","messagePattern":"TurboQuantVectorDb not initialized — call create\\(\\) before insert\\(\\)\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"turbovec-python/python/turbovec/agno.py","lineNumber":467,"sourceCode":"        else:\n            # An embedder or document without an async path at all: keep\n            # the sync fallback, but off the event loop.\n            await asyncio.to_thread(self._embed_missing, to_embed)\n\n    def _require_initialized(self) -> None:\n        \"\"\"Raise unless create() has run.\n\n        Called before any embedding work, not after it: embedding is the\n        expensive part of a write (a paid API call, GPU time), and a write\n        into an uninitialized store is doomed from the start. `insert()`\n        already failed at this boundary; `async_insert`, `upsert` and\n        `async_upsert` embedded first and only discovered it when they\n        delegated here (#473).\n        \"\"\"\n        if self._index is None:\n            # Match LanceDb's \"table not initialized\" handling: do not\n            # silently auto-create. Callers must invoke create() first.\n            raise RuntimeError(\n                \"TurboQuantVectorDb not initialized — call create() before insert().\"\n            )\n\n    def insert(\n        self,\n        content_hash: str,\n        documents: List[Document],\n        filters: Optional[Dict[str, Any]] = None,\n    ) -> None:\n        if not documents:\n            return\n        self._require_initialized()\n\n        # Merge `filters` into each document's metadata (matches LanceDb).\n        if filters:\n            for doc in documents:\n                meta = dict(doc.meta_data) if doc.meta_data else {}\n                meta.update(filters)","sourceCodeStart":449,"sourceCodeEnd":485,"githubUrl":"https://github.com/RyanCodrai/turbovec/blob/ccab9f325e6ce2a270a87daf01ae4e443bcf2d49/turbovec-python/python/turbovec/agno.py#L449-L485","documentation":"_require_initialized guards all write paths (insert, async_insert, upsert, async_upsert): if the internal index was never created, a RuntimeError is raised instead of silently auto-creating a table. Mirroring LanceDb semantics, callers must call create() first.","triggerScenarios":"Calling insert()/upsert() (or their async variants) on a TurboQuantVectorDb instance before create() was called — e.g. constructing the DB and immediately writing documents.","commonSituations":"Porting code from vector DBs that auto-create tables on first write; skipping create() in a script after adding load(); a constructor path that intentionally defers index creation (lazy init) but callers assume eager init.","solutions":["Call await db.async_create() (or db.create()) before the first insert/upsert.","Wrap write operations with an initialization check: if db._index is None or not db.exists(), create first.","If loading an existing persisted index, use the loader path that initializes _index instead of create()."],"exampleFix":"// before\nvec_db = TurboQuantVectorDb(embedder=e)\nvec_db.insert(docs)  # RuntimeError\n// after\nvec_db = TurboQuantVectorDb(embedder=e)\nif not vec_db.exists():\n    vec_db.create()\nvec_db.insert(docs)","handlingStrategy":"try-catch","validationCode":"if getattr(db, \"_index\", None) is None and not db.exists():\n    db.create()","typeGuard":"def is_initialized(db) -> bool:\n    return db._index is not None","tryCatchPattern":"try:\n    db.insert(content_hash, documents)\nexcept RuntimeError as e:\n    if \"not initialized\" in str(e):\n        db.create()\n        db.insert(content_hash, documents)","preventionTips":["Always call create() (or async_create()) immediately after constructing TurboQuantVectorDb.","Do not assume auto-create behavior from other agno vector DB backends.","Encapsulate init+write in a helper so callers cannot skip the create step."],"tags":["lifecycle","state","agno"],"backgroundTag":"invalid-state-transition","analyzedSha":"ccab9f325e6ce2a270a87daf01ae4e443bcf2d49","analyzedAt":"2026-09-06T08:39:18.516Z","contentChangedAt":"2026-09-06T08:39:18.516Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}