11.9 Pitfalls and gotchas ¶
- The auto-flip writes to the deployed copy of
application.ini, not the source tree. After a successful run,
the file at <tomcat>/webapps/ROOT/WEB-INF/backend/application.ini
has
REEMBED_ON_STARTUP = false, but
src/main/backend/application.ini (the source you build from)
still has it at true. Update the source-tree copy before your
next WAR build, or the next deploy will silently kick off a no-op
walker on startup (harmless but wastes time and logs noise).
- application.ini is gitignored, so a PR review won’t
catch a stale source copy. The example file ships
REEMBED_ON_STARTUP = false, so fresh installs start in the
right state.
EMBEDDING_DIMENSIONS must match the vector(N)
column type. If they disagree, every write fails at the database
with a vector dim mismatch. Postgres enforces this, not OwnSona —
the error surfaces at insert/update time, not at startup.
- Hard-deleted rows mid-walk don’t break the walker. If a row
is hard-deleted between the id scan and the per-batch text fetch, it
silently drops out of the batch. No re-embed, no error.
- There’s no MCP tool to trigger a re-embed. Deliberate —
admin operations stay outside the MCP surface so any LLM holding the
bearer can’t initiate them. The trigger is editing
application.ini and restarting, which is an operator action.
- Vendor neutrality is preserved. The walker doesn’t know or
care whether the provider is OpenAI, Cohere, Voyage, BGE, Ollama, or
anything else. It only knows about the
EmbeddingProvider
interface. To add a new provider, write a new EmbeddingProvider
implementation and update the instantiation in
MCPServer.<clinit> — the rest of the system (migrations,
walker, repository, tools) is provider-agnostic.