Upgrading Meilisearch
Meilisearch won't open a database that was written by an older Meilisearch version. If you start a newer Meilisearch image on an existing volume, the container exits with an error like this one:
Your database version (1.41.0) is incompatible with your current engine version (1.55.0).
Search in Karakeep stops working until the database is upgraded or rebuilt. You can either migrate the existing database in place, or start from an empty one and let Karakeep rebuild the index.
If you run a separate Meilisearch instance for embeddings (MEILI_VECTOR_ADDR),
upgrade it the same way.
Upgrading the database in place
Meilisearch can migrate an existing database while it starts. To allow it, set
MEILI_UPGRADE_DB=true (or pass --upgrade-db) when you start the new version.
Meilisearch versions older than v1.51 call this option
MEILI_EXPERIMENTAL_DUMPLESS_UPGRADE=true instead.
The migration is one-way: once it has run, older Meilisearch versions can't open the data anymore. Back up the Meilisearch volume first if you might want to go back.
Docker Compose
-
Change the image tag of the
meilisearchservice to the new version, and add the variable to its environment:services:meilisearch:image: getmeili/meilisearch:<new version>restart: unless-stoppedenv_file:- .envenvironment:MEILI_NO_ANALYTICS: "true"+ MEILI_UPGRADE_DB: "true" -
Run
docker compose up -d meilisearchand checkdocker compose logs meilisearch: Meilisearch should now start listening instead of exiting with the error above. -
Remove
MEILI_UPGRADE_DBagain and rundocker compose up -d meilisearch.
Leaving the variable set does no harm while the database is up to date, but the next image change would then migrate the data without asking.
Kubernetes
Deploy the new image as usual. The Meilisearch pod fails to start with the error above until you enable the migration:
kubectl set env deployment/meilisearch MEILI_UPGRADE_DB=true
Once the new pod is running, remove the variable again:
kubectl set env deployment/meilisearch MEILI_UPGRADE_DB-
If Flux or Argo CD manages the deployment, set and remove the variable in
your manifests instead — the next reconcile reverts kubectl set env.
Rebuilding the index instead
Karakeep can rebuild the search index from its own database, so you can also throw away the Meilisearch data:
- Stop Meilisearch and delete (or rename) the
data.msfolder in the volume mounted at/meili_data. - Start the new Meilisearch version.
- Log in to Karakeep as an administrator, go to
Admin Settings > Background Jobsand clickReindex All Bookmarks. - If embeddings are enabled
(
EMBEDDING_ENABLE_AUTO_INDEXING), also clickRegenerate Embeddings for All Bookmarks. The embeddings were stored in the same Meilisearch data, so they are gone as well.
Regenerating embeddings sends every bookmark to your embedding provider again, which can take a while and cost money on a large collection. The in-place upgrade keeps the existing embeddings.