What causes "Unsupported file source type: {type(source)}" in agentscope-ai/agentscope?

Convert the local file to Base64Source (encode bytes, set correct media_type like 'application/pdf')

agentscope-ai/agentscope · error · ValueError

Unsupported file source type

Error message

Unsupported file source type: {type(source)}

What it means

The OpenAI formatter's _format_file_source handles Base64Source and URLSource (downloading remote files and base64-encoding them into a data: URL with file_data); other source types raise this ValueError. Note it also defaults the filename to 'document.pdf' when no name is given.

Solutions

Convert the local file to Base64Source (encode bytes, set correct media_type like 'application/pdf')
Or host the file and use URLSource
Also pass a proper name so the file isn't labeled 'document.pdf'

Example fix

# before
FileBlock(source=LocalFileSource(path="report.pdf"), name="report.pdf")

# after
import base64
FileBlock(source=Base64Source(data=base64.b64encode(open("report.pdf","rb").read()).decode(), media_type="application/pdf"), name="report.pdf")

Defensive patterns

Strategy: type-guard

Validate before calling

from agentscope.message import URLSource, Base64Source
assert isinstance(block.source, (URLSource, Base64Source))

Type guard

def is_openai_file_source(src) -> bool:
    return isinstance(src, (URLSource, Base64Source))

Try / catch

try:
    formatter.format(msgs)
except ValueError as e:
    if "Unsupported file source type" in str(e):
        block.source = to_base64_source(path, "application/pdf")
        formatted = formatter.format(msgs)
    else:
        raise

Prevention

Convert local documents to Base64Source with the correct application/* media_type
Always set the block name to avoid the 'document.pdf' default
For large files prefer URLSource to avoid huge base64 payloads

When it happens

Trigger: Passing a FileBlock (e.g. PDF) whose source is a LocalFileSource, file object, or raw path to OpenAIChatFormatter.format().

Common situations: Attaching local PDFs to messages; assuming OpenAI accepts file paths directly; mixing providers where local files were handled by a different formatter.

Related errors

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/5a8a2e9ecf73920c. Report an issue: GitHub.

Appendix: source

Thrown at src/agentscope/formatter/_openai_formatter.py:218

                ``"document.pdf"``.

        Returns:
            `dict[str, Any]`:
                A dictionary with ``"type": "file"`` in OpenAI format.
        """
        if isinstance(source, Base64Source):
            data = source.data
        elif isinstance(source, URLSource):
            url_str = str(source.url)
            if url_str.startswith("file://"):
                with open(url_str.removeprefix("file://"), "rb") as f:
                    data = base64.b64encode(f.read()).decode("utf-8")
            else:
                response = requests.get(url_str, timeout=30)
                response.raise_for_status()
                data = base64.b64encode(response.content).decode("utf-8")
        else:
            raise ValueError(f"Unsupported file source type: {type(source)}")

        return {
            "type": "file",
            "file": {
                "filename": name or "document.pdf",
                "file_data": f"data:{source.media_type};base64,{data}",
            },
        }


class OpenAIChatFormatter(_OpenAIFormatterBase):
    """The OpenAI formatter class for chatbot scenario, where only a user
    and an agent are involved. We use the `name` field in OpenAI API to
    identify different entities in the conversation.
    """

    input_types: list[str] = Field(
        default_factory=lambda: [

View on GitHub (pinned to e90f1c7592)