home-assistant/core · error · HomeAssistantError

Only local attachments are currently supported

Error message

Only local attachments are currently supported

What it means

HomeAssistantError raised in ai_task._resolve_attachments when media_source.async_resolve_media() resolves the attachment's media_content_id to an item whose .path is None — i.e. the media lives on a non-local source (URL-served, e.g. web media or a remote integration) rather than the local filesystem. The LLM API needs a real file path to upload, so non-local media is rejected explicitly.

Source

Thrown at homeassistant/components/ai_task/task.py:84

            temp_filename = await hass.async_add_executor_job(
                _save_camera_snapshot, image_data
            )
            created_files.append(temp_filename)

            resolved_attachments.append(
                conversation.Attachment(
                    media_content_id=media_content_id,
                    mime_type=image_data.content_type,
                    path=temp_filename,
                )
            )
            break
        else:
            # Handle regular media sources
            media = await media_source.async_resolve_media(hass, media_content_id, None)
            if media.path is None:
                raise HomeAssistantError(
                    "Only local attachments are currently supported"
                )
            resolved_attachments.append(
                conversation.Attachment(
                    media_content_id=media_content_id,
                    mime_type=attachment.get("media_content_type") or media.mime_type,
                    path=media.path,
                )
            )

    if not created_files:
        return resolved_attachments

    def cleanup_files() -> None:
        """Cleanup temporary files."""
        for file in created_files:
            file.unlink(missing_ok=True)

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Use a local media source for attachments: pass media_content_id values rooted at media-source://media/... or another source that exposes .path.
2. For remote images, download to a local file first (e.g. via downloader or a template that writes to /media) and attach the local copy.
3. For camera frames, use a snapshot written to disk rather than the streaming URL.
4. Check that the media directory is configured (see ai_task media source error) so local resolution succeeds.

async def attachment_is_local(hass, media_content_id: str) -> bool:
    """Resolve media up front; only path-backed sources can attach."""
    from homeassistant.components import media_source

    media = await media_source.async_resolve_media(hass, media_content_id, None)
    return media.path is not None

from homeassistant.exceptions import HomeAssistantError

try:
    resolved = await _resolve_attachments(hass, session, attachments)
except HomeAssistantError as err:
    # non-local media in the list: localize it, then retry
    _LOGGER.warning("Attachment rejected (%s); download to /media first", err)
    raise

When it happens

Trigger: Calling ai_task.generate_image / generate_data with an attachments entry whose media_content_id points at a media source that serves content over HTTP(S) instead of a local path — media.path is then None and this error fires.

Common situations: Users attach media from URL-based sources (a camera snapshot served by URL, a web resource, or integrations that register URL-only media). The code above this branch already special-cases the ai_task local source; everything else must resolve to a path.

Related errors

• AI Task media source requires at least one media directory c
• AI Task entity {entity_id} does not support attachments
• 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-assisted analysis of home-assistant/core@58a3fdb3ea (2026-08-14). Data as JSON: /api/errors/0c7f8a402306176d. Report an issue: GitHub.