What causes "bytes_filename must be set when passing bytes" in FoundationAgents/MetaGPT?

Pass a descriptive filename: client.parsing(data, bytes_filename='doc.pdf').

FoundationAgents/MetaGPT · error · ValueError

bytes_filename must be set when passing bytes

Error message

bytes_filename must be set when passing bytes

What it means

Raised by OmniParseClient.get_file_info(): when file_input is raw bytes and only_bytes is False, the method needs a filename to compute a name and MIME type; without bytes_filename it cannot proceed and raises ValueError instead of guessing.

Source

Thrown at metagpt/utils/omniparse_client.py:233

            the MIME type of the file must be specified when uploading.

        Returns: [bytes, tuple]
            Returns bytes if only_bytes is True, otherwise returns a tuple (filename, file_bytes, mime_type).
        """
        if isinstance(file_input, (str, Path)):
            filename = Path(file_input).name
            file_bytes = await aread_bin(file_input)

            if only_bytes:
                return file_bytes

            mime_type = mimetypes.guess_type(file_input)[0]
            return filename, file_bytes, mime_type
        elif isinstance(file_input, bytes):
            if only_bytes:
                return file_input
            if not bytes_filename:
                raise ValueError("bytes_filename must be set when passing bytes")

            mime_type = mimetypes.guess_type(bytes_filename)[0]
            return bytes_filename, file_input, mime_type
        else:
            raise ValueError("file_input must be a string (file path) or bytes.")

View on GitHub (pinned to 11cdf466d0)

Solutions

Pass a descriptive filename: client.parsing(data, bytes_filename='doc.pdf').
If you only need the byte payload returned, call get_file_info(..., only_bytes=True).
Derive bytes_filename from the download URL or Content-Disposition before calling.

Example fix

# before
await client.parsing(resp.content)  # ValueError: bytes_filename must be set

# after
await client.parsing(resp.content, bytes_filename='downloaded.pdf')

Defensive patterns

Strategy: type-guard

Validate before calling

if isinstance(file_input, (bytes, bytearray)) and not only_bytes and not bytes_filename:
    raise ValueError('provide bytes_filename for byte input')

Type guard

def is_valid_omniparse_input(file_input, bytes_filename: str | None, only_bytes: bool) -> bool:
    if isinstance(file_input, (str, Path)):
        return True
    if isinstance(file_input, bytes):
        return only_bytes or bool(bytes_filename)
    return False

Try / catch

try:
    res = await client.parsing(data)
except ValueError as e:
    if 'bytes_filename' in str(e):
        res = await client.parsing(data, bytes_filename='upload.pdf')

Prevention

Always name byte payloads with a real extension (e.g. from Content-Disposition).
Use only_bytes=True when you don't need the filename/MIME tuple.
Prefer passing file paths when available.

When it happens

Trigger: Calling get_file_info(file_bytes, only_bytes=False) or the higher-level parse methods with bytes content but omitting bytes_filename. With only_bytes=True the bytes are returned directly and the guard is skipped.

Common situations: Fetching a document over HTTP/a memory buffer and passing response.content directly to the client without naming it; refactoring call sites that previously used file paths.

Related errors

AI-assisted analysis of FoundationAgents/MetaGPT@11cdf466d0 (2026-08-14). Data as JSON: /api/errors/afae4eb15d0daafb. Report an issue: GitHub.