home-assistant/core · error · HomeAssistantError

AI Task media source requires at least one media directory c

Error message

AI Task media source requires at least one media directory configured

What it means

HomeAssistantError thrown by ai_task's async_get_media_source singleton when hass.config.media_dirs is empty. The AI Task integration needs a writable local media directory to store generated images and expose them through its local media source; with no media directory configured there is nowhere to write, so the singleton hard-fails.

Source

Thrown at homeassistant/components/ai_task/media_source.py:19

"""Expose images as media sources."""

from pathlib import Path

from homeassistant.components.media_source import local_source
from homeassistant.core import HomeAssistant
from homeassistant.exceptions import HomeAssistantError
from homeassistant.helpers.singleton import singleton

from .const import DATA_MEDIA_SOURCE, DOMAIN, IMAGE_DIR


@singleton(DATA_MEDIA_SOURCE, async_=True)
async def async_get_media_source(hass: HomeAssistant) -> local_source.LocalSource:
    """Set up local media source."""
    media_dirs = list(hass.config.media_dirs.values())

    if not media_dirs:
        raise HomeAssistantError(
            "AI Task media source requires at least one media directory configured"
        )

    media_dir = Path(media_dirs[0]) / DOMAIN / IMAGE_DIR

    return local_source.LocalSource(
        hass,
        DOMAIN,
        "AI generated images",
        {IMAGE_DIR: str(media_dir)},
        f"/{DOMAIN}",
    )

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Configure a media directory: add media_dirs: mapping: media: /media (or your path) to configuration.yaml and restart.
2. For container installs, ensure a /media volume is mounted and referenced in media_dirs.
3. Verify with the Media Browser panel that a local source appears before retrying image generation.
4. If you cannot add media storage, avoid image-generation tasks — text/data tasks do not require the media source.

Example fix

# configuration.yaml — before
# (no media_dirs entry)

# configuration.yaml — after
media_dirs:
  media: /media

def ai_task_media_available(hass: HomeAssistant) -> bool:
    """AI Task image output needs at least one configured media dir."""
    return bool(hass.config.media_dirs)

from homeassistant.exceptions import HomeAssistantError

try:
    source = await async_get_media_source(hass)
except HomeAssistantError as err:
    _LOGGER.error("Configure media_dirs before AI Task image generation: %s", err)
    raise

When it happens

Trigger: Running any AI Task image-generation flow (ai_task.generate_image service, or a conversation agent doing image generation) on a Home Assistant instance where media_source is unconfigured — i.e. no media_dirs entries in configuration.yaml and no default media folder available.

Common situations: Fresh/minimal HA installs (especially container installs with no /media volume), users who deliberately removed media directories, or config where media_dirs: was set but empty. First image-generation attempt then fails before the LLM call.

Related errors

• Only local attachments are currently supported
• No entity_id provided and no preferred entity set
• AI Task entity {entity_id} not found
• AI Task entity {entity_id} does not support generating data
• AI Task entity {entity_id} does not support attachments

AI-assisted analysis of home-assistant/core@58a3fdb3ea (2026-08-14). Data as JSON: /api/errors/c11ef43644b85b1f. Report an issue: GitHub.