Skip to content
This repository was archived by the owner on Apr 21, 2026. It is now read-only.

Fix Jellyfin WebSocket blocking HA startup for 300s - #31

Open
erikpendragon wants to merge 1 commit into
Vansmak:mainfrom
erikpendragon:fix/jellyfin-startup-blocking
Open

Fix Jellyfin WebSocket blocking HA startup for 300s#31
erikpendragon wants to merge 1 commit into
Vansmak:mainfrom
erikpendragon:fix/jellyfin-startup-blocking

Conversation

@erikpendragon

Copy link
Copy Markdown

Problem

When the Jellyfin sensor is configured, Home Assistant logs the following at every startup:

WARNING (MainThread) [homeassistant.core] Something is blocking Home Assistant
from wrapping up the start up phase. We're going to continue anyway. Please report
the following info... The system is waiting for tasks:
{<Task pending name='Task-...' coro=<JellyfinWebSocket._listen() running at
/config/custom_components/mediarr/server/jellyfin.py:105> ...>}

Startup stalls for the full 300s timeout before HA force-continues, delaying every add-on and integration that waits for Core to reach RUNNING. Secondary symptom: the Supervisor issues secret requests, then waits ~5 min before Core responds — add-ons like Duck DNS / Samba / Node-RED appear to "hang" at boot.

Root cause

JellyfinWebSocket.connect() spawns the listener with:

self._hass.async_create_task(self._listen())

hass.async_create_task() registers the task on hass._tasks, which Core awaits during the startup phase. Since _listen() is an infinite WebSocket read loop, it never completes, so the wait always times out.

The same pattern is used in _schedule_reconnect():

delay, lambda: self._hass.async_create_task(self.connect())

A reconnect that fires during the startup window has the same effect.

Fix

Use hass.async_create_background_task(coro, name=...), which is the HA-blessed API for fire-and-forget loops that should NOT block startup. Background tasks are tracked for clean shutdown but excluded from the startup wait set.

Reference: HA developer docs — Asynchronous programming.

min_ha_version

This PR also pins min_ha_version: "2023.5.0" — the release that introduced async_create_background_task. Without this, users on older HA would install a broken integration and hit AttributeError at connect time instead of HACS / Supervisor refusing the install with a clear message. 2023.5 is nearly three years old, so the floor is uncontroversial.

Test

On a HA 2026.4.3 instance with ~200 integrations and the Jellyfin sensor configured:

STARTING → RUNNING
Before ~300s (timeout)
After ~15s
  • No "Something is blocking" warning after the fix.
  • sensor.jellyfin_mediarr still populates with library data.
  • WebSocket reconnect logic still works (verified by killing the Jellyfin instance — reconnect fires as expected without re-blocking startup).

Diff size

2 files, 4 insertions, 3 deletions. Minimal, targeted change.

JellyfinWebSocket._listen() was spawned via hass.async_create_task(),
which registers the coroutine on hass._tasks — the set Core awaits during
the startup phase. Since _listen() is an infinite WebSocket read loop,
it never completes, so Home Assistant always hits the startup-wait
timeout (300s) before continuing. The result is a ~5 minute delay on
every boot, with a "Something is blocking Home Assistant from wrapping
up the start up phase" warning naming jellyfin.py:105.

The same pattern is used in _schedule_reconnect() for the reconnect
callback, which would have the same effect if it fires during startup.

Switch both call sites to hass.async_create_background_task(), which is
the correct HA API for long-running fire-and-forget loops: background
tasks are tracked for clean shutdown but excluded from the startup wait
set.

Also pin min_ha_version to 2023.5.0 — the release that introduced
async_create_background_task — so HACS / Supervisor refuse installation
on older HA versions with a clear message rather than failing at
connect time with AttributeError.

Tested on HA 2026.4.3: STARTING->RUNNING dropped from ~300s to ~15s,
no more blocking warning, Jellyfin sensor still populates and reconnect
still works.
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant