Meilisearch Database Version Incompatible After Upgrade

How to fix it

Try these in order — the most common fix is first.

1. 1. Upgrade in place

   Copy steps
   1. Create a snapshot with POST /snapshots and wait for it to finish
   2. Stop Meilisearch and install the new binary
   3. Start with ./meilisearch --upgrade-db (older releases: --experimental-dumpless-upgrade)
   4. Watch GET /tasks?types=UpgradeDatabase
   Did this fix it? Yes No

2. 2. Migrate with a dump

   Copy steps
   1. On the old version, create a dump with POST /dumps
   2. Move data.ms and the old binary aside, install the new version
   3. Run ./meilisearch --import-dump dumps/<file>.dump --master-key=...
   4. Expect a long reindex and a memory spike
   Did this fix it? Yes No

3. 3. Read release notes

   1. Check the GitHub releases page for breaking changes before skipping versions
   Did this fix it? Yes No

Symptoms

Meilisearch fails to start after an upgrade, or reports the database is too old to be upgraded.

Why it happens

• Binary upgraded without migrating the data.ms database
• Database was created before v1.12 and can't be upgraded in place
• Skipping several versions

This guide also covers

• meilisearch database version incompatible
• meilisearch upgrade dump import
• meilisearch --upgrade-db

Other Meilisearch errors

• Meilisearch Tasks Stuck on Enqueued
• Meilisearch Indexing Slow
• Meilisearch Documents Not Showing Up
• Meilisearch Primary Key Error
• Meilisearch Filter Not Working (Attribute Not Filterable)
• Meilisearch Invalid API Key / Missing Authorization Header
• Meilisearch Disk Usage Keeps Growing / No Space Left on Device
• Meilisearch High Memory Usage