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
Open
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
When the Jellyfin sensor is configured, Home Assistant logs the following at every startup:
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:hass.async_create_task()registers the task onhass._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():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_versionThis PR also pins
min_ha_version: "2023.5.0"— the release that introducedasync_create_background_task. Without this, users on older HA would install a broken integration and hitAttributeErrorat 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:
sensor.jellyfin_mediarrstill populates with library data.Diff size
2 files, 4 insertions, 3 deletions. Minimal, targeted change.