Summary
Since upgrading to HAOS 17 (containerd snapshotter), rebuilding a local addon no longer picks up changed files. The Docker layer cache is never invalidated, even when source files have changed. This makes iterative local addon development practically impossible without workarounds.
Environment
Home Assistant OS: 17.2
Supervisor: 2026.04.x
Hardware: Raspberry Pi 5
Docker: 29.3.1
Containerd: v2.2.1 (containerd snapshotter active)
Problem description
Before HAOS 17, the typical local addon development workflow was:
Edit files in /addons/my_addon/
Click Rebuild in the HA UI
Changes are visible ✓
Since HAOS 17 with the containerd snapshotter, step 3 no longer works. The rebuild completes successfully (App successfully rebuilt) but the container still runs with the old files from the cached layer.
Verified with:
# File on disk (new version):
wc -c /addons/claudeai-arztrechnungen/index.html
→ 78919
# File inside running container (old version from cache):
docker exec addon_local_claudeai-arztrechnungen wc -c /app/index.html
→ 68469
The container consistently runs the old version regardless of how many rebuilds are done.
What I tried (none of these worked)
Attempt Result
docker system prune -af Deletes other addon images too, but COPY layer still cached
docker builder prune -af Clears legacy builder cache, containerd cache unaffected
docker buildx prune No -a flag available on HAOS
docker image rm local/aarch64-addon-...:1.0.0 -f Image deleted, but rebuild pulls from containerd layer cache
ARG CACHEBUST=<date> in Dockerfile Supervisor ignores it, still uses cached layer
Bump version in config.yaml (1.0.0 → 1.0.1) Supervisor still builds with old version tag
Change base image (node:20-alpine → node:22-alpine) New image pulled, but COPY layer still cached
ha supervisor repair No effect on build cache
ha supervisor reload No effect
Uninstall + reinstall addon Cache persists across reinstall
docker pull node:20-alpine to refresh base layer Already exists, no cache invalidation
containerd snapshot rm ... containerd CLI not available on HAOS
Root cause
The Docker containerd snapshotter stores layers by content hash. The Supervisor appears to reuse these layers without checking if the source files have changed. Since node:20-alpine is already present in the containerd store, all subsequent COPY layers are also served from cache regardless of file changes.
The build.yaml deprecation warning also appears on every build:
App uses build.yaml which is deprecated. Move build parameters into the Dockerfile directly.
Even after deleting build.yaml the warning persists, suggesting the Supervisor has its own internal cache of the addon configuration that is not refreshed.
Current workaround
Using a HA Shell Command + Automation to copy files into the running container after every start:
configuration.yaml:
shell_command:
addon_update: "docker cp /addons/my_addon/index.html addon_local_my_addon:/app/index.html"
automations.yaml:
alias: Update local addon files after start
trigger:
- platform: homeassistant
event: start
action:
- delay: "00:01:30"
- service: shell_command.addon_update
This works but requires Protection Mode to be disabled and feels like a hack that should not be necessary.
Questions
Is there an official way to clear the containerd layer cache for a specific local addon without affecting other addons?
Should the Supervisor invalidate the COPY layer cache when source files have changed (e.g. by checking file modification timestamps)?
Is this a known regression in HAOS 17 for local addon development?
Any help or guidance from the HA team or community would be much appreciated. This workflow worked perfectly before HAOS 17 and the containerd migration.