Troubleshooting
Installation & import
| Symptom |
Likely cause |
Fix |
pip install semvec fails with no matching distribution |
Python version below 3.10 |
python --version; install Python 3.10+ from python.org and re-create your venv. |
ImportError: No module named 'sentence_transformers' |
Default embedder library not installed |
pip install sentence-transformers (or pick a different embedder per Embedders). |
RuntimeError: Explicit embedder required |
Semvec needs an embedder reference; default could not auto-load |
Construct state as SemvecState(config=SemvecConfig(dimension=384)) and pass the embedder output to state.update(model.encode(text), text), or pip install sentence-transformers. |
EmbeddingError: dimension mismatch |
Your embedder produces a different vector size than SemvecConfig.dimension |
Set SemvecConfig(dimension=...) to match your model's output (e.g. 384 for MiniLM, 1536 for OpenAI text-embedding-3-small). |
Runtime
| Symptom |
Likely cause |
Fix |
| Memory keeps growing across turns |
State not persisted; many in-flight sessions |
Persist with state.to_bytes() per session; release SemvecState references when done. |
| LLM input tokens are growing, not constant |
You are sending the raw history alongside the Semvec context |
Use SemvecChatProxy (or SemvecStateSerializer) as the only context source for the LLM call. |
StateCorruptionError on from_bytes / from_dict |
Snapshot tampered or truncated |
Restore from the prior known-good snapshot. Snapshots carry an integrity checksum; corruption is detected, never silently accepted. |
| Retrieval returns irrelevant memories |
No anchors registered; topic drift |
Add a drift anchor per known domain (state.add_anchor(embed("your domain"))). |
Phase stays initialization for many turns |
Too few turns or all turns near-identical |
Normal during ramp-up; check after ~10 turns of varied input. |
Licensing
| Symptom |
Likely cause |
Fix |
LicenseError: licence required |
Pro / Enterprise feature used on Community tier |
Check tier limits in Licensing; request a trial via vertrieb@versino.de. |
LicenseExpiredError |
Licence past expiry date |
Renew via your account; replace the JWT in SEMVEC_LICENSE_KEY. |
RateLimitError |
Community-tier QPS / burst exceeded |
Catch RateLimitError and back off using its retry_after; or upgrade to Pro / Enterprise. |
REST / semvec serve
| Symptom |
Likely cause |
Fix |
Server starts but /v1/run returns 503 |
Embedder sidecar not ready |
Check logs; with --embedder-mode sidecar, wait for the daemon READY handshake; verify GPU/CPU availability. |
CORSMiddleware errors from a browser client |
Origins not configured |
Set CORS_ORIGINS=https://your-app.example.com. |
Slow /v1/run cold-starts |
First-turn embedder load |
Pre-warm with a /v1/health call after boot; persist sessions for warm-restart. |
404 Not Found on /v1/cluster/* |
Either semvec serve is not running (the routes are mounted automatically — the [cortex] extra is a marker only, no install needed), or the licence subject does not own the requested cluster. Cross-tenant requests return 404 (not 403) by design — see REST API → error handling. |
Verify the server is up (curl /v1/health), confirm the JWT subject created the cluster, and re-check the cluster id. |
401 Unauthorized on any /v1/* endpoint |
Licence JWT missing or invalid |
Set SEMVEC_LICENSE_KEY="eyJ..." before semvec serve. The SEMVEC_ALLOW_ANONYMOUS=1 development bypass is not available in the PyPI wheel (requires a local build with --features dev-anonymous). Request a Community evaluation key via vertrieb@versino.de. |
Compliance pack
| Symptom |
Likely cause |
Fix |
SqliteEventStore reports "no such table" on first use |
Schema not initialised |
Call store.init_schema() once at startup; subsequent processes pick up the existing DB. |
| Deletion certificate verifies as invalid |
Wrong public key used |
Verify against the same key that signed the certificate; rotate via the documented key-rotation flow. |
| Audit replay differs from live state |
Replay mid-stream missed a snapshot |
Run the replay from the beginning of the event log or from the most recent snapshot. |
When to escalate
- Security disclosures (vulnerabilities, data leaks): security@versino.de — coordinated disclosure preferred.
- Production outage on Pro / Enterprise: support@versino.de (SLA applies for Enterprise).
- General support: https://www.semvec.io / support@versino.de.
If you suspect a regression: include your version (python -c "import semvec; print(semvec.__version__)"), Python version, OS, and a minimal repro.