Devcontainer issues on WSL2: iptables failures and missing /run/supervisor

[Skaronator]

Hi,

I'm transitioning my local environment from the old "add-ons" devcontainer setup to the new "apps" devcontainer. Using a fresh clone of the apps-example repo on Windows 11 (WSL2 Debian and Docker Daemon running inside the Debian machine), I’m hitting a couple of "out of the box" hurdles that require manual intervention to get the Supervisor running.

Issue 1: Docker networking / iptables failure

This is a fresh cloned and started dev container build with no cache in the apps-example repository).

When running the "Start Home Assistant" task for the first time, the Supervisor fails to create the hassio network due to an iptables error.

[20:47:37] INFO: Starting local supervisor watchdog...
s6-rc: info: service legacy-services successfully started
2026-04-10 20:47:38.373 INFO (MainThread) [__main__] Initializing Supervisor setup
2026-04-10 20:47:38.373 WARNING (MainThread) [supervisor.bootstrap] Environment variable 'SUPERVISOR_DEV' is set
2026-04-10 20:47:38.500 ERROR (MainThread) [supervisor.docker.network] Can't create Supervisor network: [500] Failed to Setup IP tables: Unable to enable ACCEPT OUTGOING rule:  (iptables failed: iptables --wait -t filter -A DOCKER-FORWARD -i hassio -j ACCEPT: iptables: No chain/target/match by that name.
 (exit status 1))
Traceback (most recent call last):
  File "/usr/src/supervisor/supervisor/docker/network.py", line 69, in post_init
    self._network = network = await self.docker.networks.get(DOCKER_NETWORK)
                              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.14/site-packages/aiodocker/networks.py", line 46, in get
    data = await self.docker._query_json(f"networks/{net_specs}", method="GET")
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.14/site-packages/aiodocker/docker.py", line 541, in _query_json
    async with self._query(
               ~~~~~~~~~~~^
        path,
        ^^^^^
    ...<6 lines>...
        versioned_api=versioned_api,
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ) as response:
    ^
  File "/usr/local/lib/python3.14/contextlib.py", line 214, in __aenter__
    return await anext(self.gen)
           ^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.14/site-packages/aiodocker/docker.py", line 433, in _query
    yield await self._do_query(
          ^^^^^^^^^^^^^^^^^^^^^
    ...<9 lines>...
    )
    ^
  File "/usr/local/lib/python3.14/site-packages/aiodocker/docker.py", line 514, in _do_query
    raise DockerError(response.status, data["message"])
aiodocker.exceptions.DockerError: [404] network hassio not found

Interestingly, the Docker daemon inside the container seems to be in a weird state initially. I'm unable to create an network until I had restarted it once:

vscode ➜ /mnt/…/addons/local/apps-example (main) $ docker network create hassio
Error response from daemon: Failed to Setup IP tables: Unable to enable ACCEPT OUTGOING rule:  (iptables failed: iptables --wait -t filter -A DOCKER-FORWARD -i br-e7a4b53f819e -j ACCEPT: iptables: No chain/target/match by that name.
 (exit status 1))
vscode ➜ /mnt/…/addons/local/apps-example (main) $ sudo systemctl restart docker
vscode ➜ /mnt/…/addons/local/apps-example (main) $ docker network create hassio 
6011403328cddbe91ed1b775a7ce6ef7ecab76ca843365d43e0c11773de38fea

Issue 2: Invalid mount config (missing /run/supervisor)

After fixing issue 2 I ran in to the second issue. I started the task "Start Home Assistant" again and got this error:

2026-04-10 22:34:04.452 INFO (MainThread) [supervisor.homeassistant.core] Starting Home Assistant
2026-04-10 22:34:04.453 DEBUG (MainThread) [supervisor.bus] Fire event 'supervisor_job_start' with 'SupervisorJob(created=datetime.datetime(2026, 4, 10, 20, 34, 4, 452836, tzinfo=datetime.timezone.utc), uuid='4df5251b5eac447dafdf85905de134a9', name='home_assistant_core_start', reference=None, progress=0, stage=None, parent_id='3ab5097c4b004a53979edf76aaa7536e', done=None, on_change=<bound method JobManager._on_job_change of <supervisor.jobs.JobManager object at 0x7ddc9c8242f0>>, internal=False, errors=[], release_event=None, extra=None, child_job_syncs=None, parent_job_syncs=[])'
2026-04-10 22:34:04.455 DEBUG (MainThread) [supervisor.homeassistant.api] Core container is not running
2026-04-10 22:34:04.455 DEBUG (MainThread) [supervisor.homeassistant.api] Can't connect to Home Assistant API: Core container is not running
2026-04-10 22:34:04.455 DEBUG (MainThread) [supervisor.homeassistant.websocket] Can't send WebSocket command: Can't connect to Home Assistant Core WebSocket, the API is not reachable
2026-04-10 22:34:04.462 INFO (MainThread) [supervisor.homeassistant.module] Update pulse/client.config: /data/tmp/homeassistant_pulse
2026-04-10 22:34:04.462 DEBUG (MainThread) [supervisor.bus] Fire event 'supervisor_job_start' with 'SupervisorJob(created=datetime.datetime(2026, 4, 10, 20, 34, 4, 462562, tzinfo=datetime.timezone.utc), uuid='136acf17166c47d5aaa73e9dff890f08', name='docker_home_assistant_run', reference='homeassistant', progress=0, stage=None, parent_id='4df5251b5eac447dafdf85905de134a9', done=None, on_change=<bound method JobManager._on_job_change of <supervisor.jobs.JobManager object at 0x7ddc9c8242f0>>, internal=False, errors=[], release_event=None, extra=None, child_job_syncs=None, parent_job_syncs=[])'
2026-04-10 22:34:04.465 DEBUG (MainThread) [supervisor.bus] Fire event 'supervisor_job_start' with 'SupervisorJob(created=datetime.datetime(2026, 4, 10, 20, 34, 4, 465003, tzinfo=datetime.timezone.utc), uuid='482d7b44f8104a80bd1bc507e13c6c64', name='docker_interface_stop', reference='homeassistant', progress=0, stage=None, parent_id='136acf17166c47d5aaa73e9dff890f08', done=None, on_change=<bound method JobManager._on_job_change of <supervisor.jobs.JobManager object at 0x7ddc9c8242f0>>, internal=False, errors=[], release_event=None, extra=None, child_job_syncs=None, parent_job_syncs=[])'
2026-04-10 22:34:04.466 DEBUG (MainThread) [supervisor.homeassistant.api] Core container is not running
2026-04-10 22:34:04.466 DEBUG (MainThread) [supervisor.homeassistant.api] Can't connect to Home Assistant API: Core container is not running
2026-04-10 22:34:04.466 DEBUG (MainThread) [supervisor.homeassistant.websocket] Can't send WebSocket command: Can't connect to Home Assistant Core WebSocket, the API is not reachable
2026-04-10 22:34:04.467 DEBUG (MainThread) [supervisor.bus] Fire event 'supervisor_job_end' with 'SupervisorJob(created=datetime.datetime(2026, 4, 10, 20, 34, 4, 465003, tzinfo=datetime.timezone.utc), uuid='482d7b44f8104a80bd1bc507e13c6c64', name='docker_interface_stop', reference='homeassistant', progress=100, stage=None, parent_id='136acf17166c47d5aaa73e9dff890f08', done=False, on_change=<bound method JobManager._on_job_change of <supervisor.jobs.JobManager object at 0x7ddc9c8242f0>>, internal=False, errors=[], release_event=None, extra=None, child_job_syncs=None, parent_job_syncs=[])'
2026-04-10 22:34:04.470 ERROR (MainThread) [supervisor.docker.manager] Can't create container from ghcr.io/home-assistant/qemux86-64-homeassistant:2026.5.0.dev202604100315: [400] invalid mount config for type "bind": bind source path does not exist: /run/supervisor
2026-04-10 22:34:04.470 DEBUG (MainThread) [supervisor.bus] Fire event 'supervisor_job_end' with 'SupervisorJob(created=datetime.datetime(2026, 4, 10, 20, 34, 4, 462562, tzinfo=datetime.timezone.utc), uuid='136acf17166c47d5aaa73e9dff890f08', name='docker_home_assistant_run', reference='homeassistant', progress=0, stage=None, parent_id='4df5251b5eac447dafdf85905de134a9', done=False, on_change=<bound method JobManager._on_job_change of <supervisor.jobs.JobManager object at 0x7ddc9c8242f0>>, internal=False, errors=[SupervisorJobError(type_=<class 'supervisor.exceptions.DockerAPIError'>, message='Can\'t create container from ghcr.io/home-assistant/qemux86-64-homeassistant:2026.5.0.dev202604100315: [400] invalid mount config for type "bind": bind source path does not exist: /run/supervisor', stage=None, error_key=None, extra_fields=None)], release_event=None, extra=None, child_job_syncs=None, parent_job_syncs=[])'
2026-04-10 22:34:04.471 DEBUG (MainThread) [supervisor.bus] Fire event 'supervisor_job_end' with 'SupervisorJob(created=datetime.datetime(2026, 4, 10, 20, 34, 4, 452836, tzinfo=datetime.timezone.utc), uuid='4df5251b5eac447dafdf85905de134a9', name='home_assistant_core_start', reference=None, progress=0, stage=None, parent_id='3ab5097c4b004a53979edf76aaa7536e', done=False, on_change=<bound method JobManager._on_job_change of <supervisor.jobs.JobManager object at 0x7ddc9c8242f0>>, internal=False, errors=[SupervisorJobError(type_=<class 'supervisor.exceptions.HomeAssistantError'>, message='', stage=None, error_key=None, extra_fields=None)], release_event=None, extra=None, child_job_syncs=None, parent_job_syncs=[])'
2026-04-10 22:34:04.471 ERROR (MainThread) [supervisor.homeassistant.core] Can't start Home Assistant!

Here the full log: first.log

The folder just doesn't exist:

vscode ➜ /mnt/…/addons/local/apps-example (main) $ ls -lsah /run/supervisor
ls: cannot access '/run/supervisor': No such file or directory
vscode ➜ /mnt/…/addons/local/apps-example (main) $ ls -lsah /run/          
total 8.0K
   0 drwxr-xr-x 18 root root    460 Apr 10 20:32 .
4.0K drwxr-xr-x  1 root root   4.0K Apr 10 20:29 ..
   0 drwx--x--x  7 root root    180 Apr 10 20:30 containerd
   0 drwxr-xr-x  2 root root     40 Apr 10 20:29 credentials
   0 drwxr-xr-x  2 root root     60 Apr 10 20:29 dbus
   0 drwx------  7 root root    160 Apr 10 20:32 docker
4.0K -rw-r--r--  1 root root      4 Apr 10 20:32 docker.pid
   0 srw-rw----  1 root docker    0 Apr 10 20:29 docker.sock
   0 prw-------  1 root root      0 Apr 10 20:29 initctl
   0 drwxrwxrwt  3 root root     60 Apr 10 20:29 lock
   0 drwxr-xr-x  3 root root     60 Apr 10 20:29 log
   0 drwxr-xr-x  2 root root     40 Apr 10 20:29 mount
   0 drwxr-xr-x  4 root root     80 Apr 10 20:29 NetworkManager
   0 drwxr-xr-x  2 root root     40 Apr 10 20:29 sendsigs.omit.d
   0 drwxr-xr-x  2 root root     40 Apr 10 20:29 setrans
   0 lrwxrwxrwx  1 root root      8 Apr 10 20:29 shm -> /dev/shm
   0 drwxr-xr-x  2 root root     40 Apr 10 20:29 sshd
   0 drwx--x--x  2 root root     40 Apr 10 20:29 sudo
   0 drwxr-xr-x 23 root root    620 Apr 10 20:32 systemd
   0 drwxr-xr-x  8 root root    180 Apr 10 20:40 udev
   0 drwx------  2 root root     40 Apr 10 20:29 udisks2
   0 drwxr-xr-x  2 root root     40 Apr 10 20:29 user
   0 -rw-------  1 root root      0 Apr 10 20:30 xtables.lock

After creating this folder (mkdir /run/supervisor) and re-running the "Start Home Assistant" task, the UI and HA instance load as expected (though the health check still shows some warnings).

Here the full log: second.log

---

It feels like the devcontainer initialization might need to ensure iptables modules are properly loaded or that the Docker service is fully "ready" before the Supervisor takes over.

Additionally, adding /run/supervisor to the devcontainer's creation script (or as a volume in devcontainer.json) might solve Issue 2.

Is anyone else seeing this on WSL2, or is my setup just being "special"?

Thanks

[Skaronator]

Changing the task command to this consistently fixes it for me:

      "label": "Start Home Assistant",
      "type": "shell",
-     "command": "supervisor_run",
+     "command": "sudo systemctl restart docker && sudo mkdir -p /run/supervisor && supervisor_run",

This can't be the real solution but I was able to get home assistant consistently working with this change on my WSL machine (which might be cursed). Although health check still fail:

2026-04-10 23:12:28.595 DEBUG (MainThread) [supervisor.homeassistant.api] Error on call http://localhost/api/core/state: Cannot connect to unix socket /run/os/core.sock ssl:False [No such file or directory]
2026-04-10 23:12:28.595 DEBUG (MainThread) [supervisor.homeassistant.api] Can't connect to Home Assistant API: Cannot connect to unix socket /run/os/core.sock ssl:False [No such file or directory]

[agners]

If you have to create a list with issue 1 and 2, then probably it is a good idea to open two issues 😉

Anyhow, Issue 1 I've also encountered while testing, see #162 (comment). It does seem to be some WSL2 artefact, some race condition during Docker daemon startup. I haven't found any official reports/acknowledgement to it.

I've just seen Microsoft Upgrades Its WSL2 Kernel Against Linux 6.18 LTS article on Phoronix, before introducing any work around we should retest with that version.

As for Issue 2: This is a genuine error, the supervisor_run script needs updating. I'll create a PR for this.

[MelchMwoan]

Just to confirm, i'm having the same issues.

After changing the task to sudo systemctl restart docker && sudo mkdir -p /run/supervisor && supervisor_run, the devcontainer starts. However i'm seeing the same issues with healthcheck and another issue when calling from within my add-on/app: curl http://supervisor/core/api/template -H "Authorization: Bearer $SUPERVISOR_TOKEN" which results in a 502: Bad Gateway due to the supervisor not being able to reach the core.

Looks like the run/os/core.sock is never created and/or mounted to either the homeassistant or the hassio_supervisor containers which causes the supervisor to not be able to reach the core api and therefore failing healthchecks and other requests.