Recovering and Maintaining Uptime Kuma (SQLite)

Applies to: Uptime Kuma running on Raspberry Pi via Docker/Dockge.

Primary Error: SQLITE_CORRUPT: database disk image is malformed

1. Database Recovery Procedure

If Uptime Kuma fails to start and logs show a "database malformed" error, the SQLite internal structure is corrupted. Use a temporary Alpine container to repair it without installing local dependencies.

Step 1: Stop the Stack

In the Dockge UI, stop the Uptime Kuma container to release file locks.

Step 2: Run the Repair Command

Navigate to your stack folder (e.g., /opt/stacks/uptime-kuma) and run:

docker run --rm -v $(pwd):/data -w /data alpine:latest \
sh -c "apk add --no-cache sqlite && sqlite3 kuma.db '.recover' | sqlite3 kuma_new.db"

Step 3: Swap the Database Files

If kuma_new.db has a file size greater than 0, replace the broken database:

mv kuma.db kuma.db.broken
mv kuma_new.db kuma.db
chmod 666 kuma.db

2. Setting Data Retention (30-Day Limit)

To prevent the database from growing too large—which slows down the Pi and increases corruption risk—limit the history.

1. Log into Uptime Kuma.

2. Navigate to Settings > Monitor History.

3. Set Keep monitor history for X days to 30.

4. Scroll to the bottom and click Save.

[!TIP] Why 30 days? On an SD card, every "write" operation has a cost. Limiting retention reduces the frequency of disk writes and keeps the database snappy.

3. Shrinking the Database (VACUUM)

Deleting records (Step 2) does not automatically reduce the file size on disk; it leaves "empty holes" in the file. To reclaim space:

1. Go to Settings > Monitor History.

2. Click the Shrink Database button.

3. Wait: The UI may become unresponsive for 1–2 minutes while the database is rebuilt.

4. Verify the file size has decreased using ls -lh kuma.db in the terminal.

4. Manual Backup Procedure

Before making major changes or updates, perform a manual "cold backup."

1. Stop the stack in Dockge.

2. Copy the file with a timestamp:

    

   cp kuma.db kuma.db.backup_$(date +%F)
   

3. Restart the stack.

5. Prevention Checklist for Raspberry Pi

• Power: Use an official Raspberry Pi Power Supply to avoid "under-voltage" events.

• Storage: Consider migrating from an SD Card to a USB SSD for better database reliability.

• Export: Periodically use the Settings > Backup feature in the Kuma UI to download a .json copy of your monitors and settings.