ha:blocking-io-check
Detect blocking I/O on the event loop specifically — sync library calls inside async def, imports and file-exists checks as hidden I/O, and unbatched executor jobs. Use when blocking I/O is suspected,
SKILL.mdskills/blocking-io-check/SKILL.md
GitHubBlocking-I/O Detection
Identify and fix blocking-I/O anti-patterns in Home Assistant async code.
Orientation: this is the event-loop analogue of hunting an N+1 query — instead of a query per row, the smell is a blocking call per iteration (or a hidden sync call) stalling the single event loop that runs all of Home Assistant. Companion review agent:
blocking-io-auditor.
Iron Laws - Never Violate These
- Never call blocking I/O in an async context (P4) — sync library calls,
open(),requests.*,time.sleep,urllib,json.loadon a file,os.path.exists/Path.existsinside anasync defblock the whole loop. "don't do blocking I/O in the event loop, even in tests" — MartinHjelmare, https://github.com/home-assistant/core/pull/154625#discussion_r2619211602 - Do blocking work in the executor, batched into one job (P4) — wrap sync work in
hass.async_add_executor_job; combine several sync calls into a single job rather than scheduling many. Never run executor jobs concurrently as a substitute for an async library. - Imports and file-exists are I/O — move them (P4) — module imports inside a function and filesystem probes cause I/O; import at module top-level or defer to the executor. "we should not do imports here as that causes IO" — joostlek, https://github.com/home-assistant/core/pull/174058#discussion_r3438274629
- A function that never awaits must not be a coroutine (PS19) — decorate it
@callbackinstead ofasync def; and don't hop async→sync→async. "Why is this a coroutine function if we don't await inside?" — MartinHjelmare, https://github.com/home-assistant/core/pull/153268#discussion_r2468783062
Detection Patterns
Pattern 1: Loop with a blocking call
# BAD: one blocking sync call per iteration stalls the loop N times
async def async_update(self) -> None:
for device in self.devices:
device.state = self.client.read_sync(device.id) # sync call in async def!
# GOOD: one executor job for the whole batch (P4)
async def async_update(self) -> None:
states = await self.hass.async_add_executor_job(self._read_all)
def _read_all(self) -> dict[str, State]:
return {d.id: self.client.read_sync(d.id) for d in self.devices}
Pattern 2: Blocking call directly in async def
# BAD: sync file / HTTP / sleep on the event loop
async def async_setup_entry(hass, entry):
config = json.loads(open(path).read()) # open() + read() block
resp = requests.get(url) # requests blocks
time.sleep(2) # sleep blocks the WHOLE loop
# GOOD: executor for sync file work, async library for HTTP, async sleep
async def async_setup_entry(hass, entry):
config = await hass.async_add_executor_job(_load_config, path)
session = async_get_clientsession(hass)
resp = await session.get(url)
await asyncio.sleep(2)
Pattern 3: Hidden I/O — imports and filesystem probes
# BAD: import inside the function (I/O on first call) + a filesystem probe on the loop
async def async_get_device(hass):
import heavy_library # import is I/O (joostlek)
if os.path.exists(cache_path): # Path.exists() / os.path.exists() is I/O
...
# GOOD: import at module top-level; probe the filesystem in the executor
import heavy_library # top of file
async def async_get_device(hass):
exists = await hass.async_add_executor_job(cache_path.exists)
...
Quick Detection Commands
Use Grep to find known blocking calls inside async code (P4 mechanical check list):
Search integration files for open(, requests., time.sleep, urllib, json.load,
import_module, os.path.exists, .exists(), and socket. — then read each hit to confirm
it sits inside an async def body (or a @callback) rather than an executor target.
Use Grep to find async def functions and scan their bodies for any await — a coroutine
with no await should be a @callback (PS19).
Use Grep to find async_add_executor_job calls inside loops (for, while,
comprehensions) — several jobs that should be batched into one (P4).
Ruff's ASYNC rule family (flake8-async) flags many of these mechanically; the HA runtime
also ships a blocking-call detector that raises at runtime when a known blocking call executes
on the loop.
Analysis Command
For a coordinator or setup module, run:
Use Grep to list every call in the async update / setup path, then verify each one is either
awaited (async library), wrapped in a single hass.async_add_executor_job, or a pure
non-I/O computation. Any bare sync I/O call, in-function import, or filesystem probe on the
loop is a P4 violation.
Then confirm sync work is batched — one executor job per logical fetch, not one per device.
References
For detailed patterns, see:
${CLAUDE_SKILL_DIR}/references/executor-patterns.md- Executor batching and offloading techniques (one job over many, avoiding concurrent executor jobs, streaming large sync reads)${CLAUDE_SKILL_DIR}/references/async-io-patterns.md- Async-library and@callbackpatterns: wrapping sync libraries, scheduling from the loop, dispatcher/subscription setup, anti-patterns