Fixing Unclean Home Assistant Shutdown

Installation
1

If you’re running Home Assistant in Docker and seeing this error after restarts:

WARNING (Recorder) [homeassistant.components.recorder.util] The system could not validate that the sqlite3 database at //config/home-assistant_v2.db was shutdown cleanly
WARNING (Recorder) [homeassistant.components.recorder.util] Ended unfinished session (id=296 from 2025-11-30 06:16:40.287699)

This means Home Assistant’s database wasn’t closed properly before the container was killed. I’ve hit this twice now, from two different causes.

Cause 1: Docker Daemon Upgrades

When apt automatically upgrades docker-ce (typically around 6 AM), it restarts the Docker daemon, which forcefully stops all containers. The default shutdown timeout is only 15 seconds, which isn’t always enough for Home Assistant to flush its database.

Fix: Increase Docker’s shutdown timeout in /etc/docker/daemon.json:

{
  "shutdown-timeout": 120
}

This gives containers 120 seconds to stop gracefully during Docker daemon restarts.

Cause 2: Watchtower Not Waiting

If you use Watchtower to auto-update containers, the original repository is unmaintained and doesn’t wait long enough for containers to stop gracefully.

Fix: Switch to the maintained fork and configure proper timeouts in your docker-compose.yml:

services:
  watchtower:
    image: nickfedor/watchtower  # A fork which is actually being updated!
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      WATCHTOWER_TIMEOUT: 120s  # Give containers 120 seconds to stop gracefully
      WATCHTOWER_CLEANUP: "true"
    network_mode: host
    command: --interval 10800 homeassistant  # 10800 for 3h
    restart: unless-stopped

The key is WATCHTOWER_TIMEOUT: 120s which gives Home Assistant enough time to cleanly close its database before being killed.

Both of these fixes have eliminated the unclean shutdown warnings in my setup.
I hope this helps others who have found this issue too!

2

Rather than setting this globally you should use stop_grace_period if needed.

1 Like