{"record":{"id":"c11ef43644b85b1f","repo":"home-assistant/core","slug":"ai-task-media-source-requires-at-least-one-media-d","errorCode":null,"errorMessage":"AI Task media source requires at least one media directory configured","messagePattern":"AI Task media source requires at least one media directory configured","errorType":"exception","errorClass":"HomeAssistantError","httpStatus":null,"severity":"error","filePath":"homeassistant/components/ai_task/media_source.py","lineNumber":19,"sourceCode":"\"\"\"Expose images as media sources.\"\"\"\n\nfrom pathlib import Path\n\nfrom homeassistant.components.media_source import local_source\nfrom homeassistant.core import HomeAssistant\nfrom homeassistant.exceptions import HomeAssistantError\nfrom homeassistant.helpers.singleton import singleton\n\nfrom .const import DATA_MEDIA_SOURCE, DOMAIN, IMAGE_DIR\n\n\n@singleton(DATA_MEDIA_SOURCE, async_=True)\nasync def async_get_media_source(hass: HomeAssistant) -> local_source.LocalSource:\n    \"\"\"Set up local media source.\"\"\"\n    media_dirs = list(hass.config.media_dirs.values())\n\n    if not media_dirs:\n        raise HomeAssistantError(\n            \"AI Task media source requires at least one media directory configured\"\n        )\n\n    media_dir = Path(media_dirs[0]) / DOMAIN / IMAGE_DIR\n\n    return local_source.LocalSource(\n        hass,\n        DOMAIN,\n        \"AI generated images\",\n        {IMAGE_DIR: str(media_dir)},\n        f\"/{DOMAIN}\",\n    )\n","sourceCodeStart":1,"sourceCodeEnd":32,"githubUrl":"https://github.com/home-assistant/core/blob/58a3fdb3ea0538617f0a07efcfba6294de64fd59/homeassistant/components/ai_task/media_source.py#L1-L32","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Configure a media directory: add media_dirs: mapping: media: /media (or your path) to configuration.yaml and restart.","For container installs, ensure a /media volume is mounted and referenced in media_dirs.","Verify with the Media Browser panel that a local source appears before retrying image generation.","If you cannot add media storage, avoid image-generation tasks — text/data tasks do not require the media source."],"exampleFix":"# configuration.yaml — before\n# (no media_dirs entry)\n\n# configuration.yaml — after\nmedia_dirs:\n  media: /media","handlingStrategy":"validation","validationCode":"def ai_task_media_available(hass: HomeAssistant) -> bool:\n    \"\"\"AI Task image output needs at least one configured media dir.\"\"\"\n    return bool(hass.config.media_dirs)","typeGuard":null,"tryCatchPattern":"from homeassistant.exceptions import HomeAssistantError\n\ntry:\n    source = await async_get_media_source(hass)\nexcept HomeAssistantError as err:\n    _LOGGER.error(\"Configure media_dirs before AI Task image generation: %s\", err)\n    raise","preventionTips":["Add media_dirs to configuration.yaml before enabling any image-generation automation.","Mount a persistent /media volume in container installs.","Smoke-test with one UI image generation after configuring media storage."],"tags":["homeassistant","ai-task","media-source","configuration"],"backgroundTag":null,"analyzedSha":"58a3fdb3ea0538617f0a07efcfba6294de64fd59","analyzedAt":"2026-08-14T20:54:38.818Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}