microsoft/markitdown · error · ValueError

Unsupported file URI: {uri}. Netloc must be empty or localho

Error message

Unsupported file URI: {uri}. Netloc must be empty or localhost.

What it means

In convert_uri(), URIs starting with file: are parsed with file_uri_to_path(); RFC 8089 allows an authority (netloc) only for localhost. Any other host in the authority (file://server/share.docx) is rejected with this ValueError because the library only reads local filesystem paths.

Source

Thrown at packages/markitdown/src/markitdown/_markitdown.py:445

    def convert_uri(
        self,
        uri: str,
        *,
        stream_info: Optional[StreamInfo] = None,
        file_extension: Optional[str] = None,  # Deprecated -- use stream_info
        mock_url: Optional[
            str
        ] = None,  # Mock the request as if it came from a different URL
        **kwargs: Any,
    ) -> DocumentConverterResult:
        uri = uri.strip()

        # File URIs
        if uri.startswith("file:"):
            netloc, path = file_uri_to_path(uri)
            if netloc and netloc != "localhost":
                raise ValueError(
                    f"Unsupported file URI: {uri}. Netloc must be empty or localhost."
                )
            return self.convert_local(
                path,
                stream_info=stream_info,
                file_extension=file_extension,
                url=mock_url,
                **kwargs,
            )
        # Data URIs
        elif uri.startswith("data:"):
            mimetype, attributes, data = parse_data_uri(uri)

            base_guess = StreamInfo(
                mimetype=mimetype,
                charset=attributes.get("charset"),
            )
            if stream_info is not None:

View on GitHub (pinned to fd239d5d2b)

Solutions

1. Use a three-slash local URI: file:///mnt/nas/share/report.docx (mount the share locally first)
2. Use file://localhost/path only if you truly mean the local machine
3. Or skip the URI and pass the local path directly: md.convert('/mnt/nas/share/report.docx')

Example fix

# before
md.convert_uri("file://nas/report.docx")  # ValueError

# after
md.convert_uri("file:///mnt/nas/report.docx")
# or
md.convert("/mnt/nas/report.docx")

from urllib.parse import urlparse

def is_local_file_uri(uri: str) -> bool:
    p = urlparse(uri)
    return p.scheme == "file" and p.netloc in ("", "localhost")

try:
    result = md.convert_uri(uri)
except ValueError as e:
    if "Netloc must be empty or localhost" in str(e):
        raise ValueError(f"Remote file URI not supported; mount it locally: {uri}") from e
    raise

When it happens

Trigger: md.convert_uri('file://nas/share/report.docx') or any file URI whose netloc is a hostname other than localhost (note: file://localhost/... IS accepted).

Common situations: Copy-pasting UNC paths as file:// URIs from Windows Explorer or Office hyperlinks, or generating file URIs from network mounts without normalizing the authority.

Related errors

• Unsupported URI scheme: {uri.split(':')[0]}. Supported schem
• Not a file URL: {file_uri}
• Not a data URI
• Malformed data URI, missing ',' separator
• Error converting .ipynb file: {str(e)}

AI-assisted analysis of microsoft/markitdown@fd239d5d2b (2026-08-14). Data as JSON: /api/errors/5dbb5600353b2d1a. Report an issue: GitHub.