Meilisearch Snapshot Backup Guide: Production Implementation & Recovery

Understanding Meilisearch Snapshots in Production

When designing resilient search infrastructure, evaluating Self-Hosted vs Managed Search Services dictates your data persistence strategy. Meilisearch snapshots capture a consistent, point-in-time state of the underlying LMDB database. This process also archives the pending task queue for exact state reconstruction.

Snapshots operate asynchronously. They do not block active read queries during creation. This mechanism differs fundamentally from live replication, which requires continuous network synchronization. File-based snapshots provide a reliable fallback for index corruption or catastrophic node failure.

Pre-Flight Validation & System Requirements

Verify available storage exceeds 1.5x the current data.ms directory size. Insufficient space causes immediate LMDB write failures. Ensure the meilisearch process user holds explicit write access to the configured --snapshot-dir path.

Cross-reference the running binary version with snapshot metadata. LMDB format changes between major releases prevent direct restoration. Execute these pre-flight checks before initiating any backup routine:

# Check disk space and inode availability
df -h /var/lib/meilisearch && df -i /var/lib/meilisearch

# Verify snapshot directory ownership and permissions
ls -ld /var/lib/meilisearch/snapshots

Triggering Snapshots via REST API & CLI

Snapshots are generated asynchronously via the REST API. Issue a POST /snapshots request with an empty JSON payload. The endpoint returns a taskUid immediately. Monitor the task status until it resolves to succeeded.

# Trigger snapshot creation
curl -X POST 'http://localhost:7700/snapshots' \
 -H 'Authorization: Bearer <MASTER_KEY>' \
 -H 'Content-Type: application/json' \
 -d '{}'

Poll the task endpoint using a 5-second interval. Set a hard timeout threshold of 300s for large datasets. Monitor the configured directory for .snapshot archive generation. Do not interrupt the process mid-write to avoid corrupted LMDB pages.

# Poll task status (repeat every 5s)
curl -s "http://localhost:7700/tasks/<TASK_UID>" | jq '.status'

Debugging Snapshot Failures & Lock Contention

Inspect service logs for IOError or MdbError traces when backups fail. Common failure modes include disk exhaustion, permission denials, and concurrent write locks. Run these diagnostic steps to isolate the root cause:

  1. Check disk I/O and available inodes: df -h /var/lib/meilisearch && df -i /var/lib/meilisearch
  2. Verify snapshot directory permissions: ls -ld /var/lib/meilisearch/snapshots
  3. Parse service logs for LMDB errors: grep -i 'mdb\|snapshot\|ioerror' /var/log/meilisearch/meilisearch.log
  4. Monitor task queue depth during backup: curl -s http://localhost:7700/tasks?statuses=processing | jq '.results[].status'

Apply these resolution paths based on log output:

  • Disk Full: Archive old snapshots to S3/GCS, clear local directory, retry API call.
  • Version Mismatch: Export data via POST /dumps instead, upgrade binary, restore dump.
  • Lock Contention: Pause ingestion workers, wait for active tasks to drain (GET /tasks?statuses=processing returns empty), trigger snapshot.
  • Corrupted Archive: Validate checksum, regenerate from primary node, verify LMDB integrity with mdb_stat.

Implement exponential backoff in your orchestration layer. This prevents resource starvation during high-throughput ingestion windows.

Restoring Snapshots & Resuming Indexing Pipelines

Stop the Meilisearch service completely before attempting restoration. Extract the .snapshot archive into a clean data.ms directory. Start the service using the import flag to trigger automatic LMDB reconstruction.

# Stop service
sudo systemctl stop meilisearch

# Clear existing data directory
sudo rm -rf /var/lib/meilisearch/data.ms

# Extract snapshot archive
sudo tar -xf /path/to/meilisearch-YYYY-MM-DD.snapshot -C /var/lib/meilisearch/

# Start with import flag
meilisearch --snapshot-dir /var/lib/meilisearch/snapshots \
 --import-snapshot /path/to/meilisearch-YYYY-MM-DD.snapshot

Validate index health via GET /indexes. Confirm numberOfDocuments matches pre-backup metrics exactly. Resume external indexing pipelines only after GET /health returns available. This sequence guarantees zero data loss during recovery operations.

Automating Backups & Infrastructure Alignment

Integrate snapshot triggers into Kubernetes CronJobs or systemd timers. Apply strict retention policies to prevent unbounded storage growth. Align automated backup cadence with your data ingestion velocity and RPO targets.

Schedule off-peak execution windows to minimize I/O contention. Use lifecycle rules to automatically purge archives older than your compliance window. Properly orchestrating these workflows ensures your search layer scales predictably within a modern Search Engine Selection & Architecture framework.