home-assistant/core · error · HomeAssistantError

AI Task media source requires at least one media directory…

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.

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
• AI Task entity does not support attachments
• AI Task entity does not support generating data
• AI Task entity does not support generating images
• AI Task entity not found

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

Appendix: 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)