xtekky/gpt4free · error · ValueError

MarkItDown requires media to be provided.

Error message

MarkItDown requires media to be provided.

What it means

ValueError from MarkItDown.create_async_generator when the media argument is None. MarkItDown converts documents to text; unlike chat providers it operates on files/URLs, so at least one media entry (file object, path, or URL) is required and the provider fails fast before checking whether markitdown is even installed.

Source

Thrown at g4f/Provider/audio/MarkItDown.py:26

    has_markitdown = True
except ImportError:
    has_markitdown = False

from ...typing import AsyncResult, Messages, MediaListType
from ...tools.files import get_tempfile
from ..base_provider import AsyncGeneratorProvider, ProviderModelMixin


class MarkItDown(AsyncGeneratorProvider, ProviderModelMixin):
    working = has_markitdown

    @classmethod
    async def create_async_generator(
        cls, model: str, messages: Messages, media: MediaListType = None, **kwargs
    ) -> AsyncResult:
        if media is None:
            raise ValueError("MarkItDown requires media to be provided.")
        if not has_markitdown:
            raise ImportError(
                "MarkItDown is not installed. Please install it with `pip install markitdown`."
            )
        md = MaItDo()
        for file, filename in media:
            text = None
            try:
                if isinstance(file, str) and file.startswith(("http://", "https://")):
                    result = md.convert_url(file)
                else:
                    result = md.convert(
                        file,
                        stream_info=StreamInfo(filename=filename) if filename else None,
                    )
                if asyncio.iscoroutine(result.text_content):
                    text = await result.text_content
                else:

View on GitHub (pinned to 973504e177)

Solutions

  1. Attach the document: pass media=[(open('doc.pdf','rb'), 'doc.pdf')] or a URL entry
  2. Use a different provider for plain-text chat requests
  3. Validate that media is non-empty before selecting MarkItDown as provider

Example fix

# before
resp = await client.chat.completions.create(model='MarkItDown', messages=msgs)

# after
resp = await client.chat.completions.create(model='MarkItDown', messages=msgs, media=[('https://example.com/report.pdf', 'report.pdf')])
Defensive patterns

Strategy: validation

Validate before calling

def has_media(media):
    return bool(media) and len(media) > 0

if provider_name == 'MarkItDown' and not has_media(media):
    raise ValueError('MarkItDown requires an attachment')

Type guard

from g4f.typing import MediaListType

def is_non_empty_media(media: MediaListType | None) -> bool:
    return media is not None and len(media) > 0

Try / catch

except ValueError as e:
    if 'requires media' in str(e):
        return 'No document attached.'  # user-facing message

Prevention

When it happens

Trigger: Routing a plain text-only chat request to the MarkItDown provider, i.e. no media supplied via the media parameter of the request.

Common situations: Misconfigured client with provider='MarkItDown' for normal chat; upload forms where the file field was left empty; orchestration code forgetting to attach media.

Related errors

AI-assisted analysis of xtekky/gpt4free@973504e177 (2026-08-14). Data as JSON: /api/errors/1babbc14539fad25. Report an issue: GitHub.