microsoft/markitdown · error · ValueError

Not a file URL: {file_uri}

Error message

Not a file URL: {file_uri}

What it means

file_uri_to_path() parses the URI with urlparse and requires scheme == 'file'; anything else raises ValueError with the offending URI echoed. Inside convert_uri() it is only called after a startswith('file:') check, so end users normally see this only when calling the utility directly.

Source

Thrown at packages/markitdown/src/markitdown/_uri_utils.py:12

import base64
import os
from typing import Tuple, Dict
from urllib.request import url2pathname
from urllib.parse import urlparse, unquote_to_bytes


def file_uri_to_path(file_uri: str) -> Tuple[str | None, str]:
    """Convert a file URI to a local file path"""
    parsed = urlparse(file_uri)
    if parsed.scheme != "file":
        raise ValueError(f"Not a file URL: {file_uri}")

    netloc = parsed.netloc if parsed.netloc else None
    path = os.path.abspath(url2pathname(parsed.path))
    return netloc, path


def parse_data_uri(uri: str) -> Tuple[str | None, Dict[str, str], bytes]:
    if not uri.startswith("data:"):
        raise ValueError("Not a data URI")

    header, _, data = uri.partition(",")
    if not _:
        raise ValueError("Malformed data URI, missing ',' separator")

    meta = header[5:]  # Strip 'data:'
    parts = meta.split(";")

    is_base64 = False

View on GitHub (pinned to fd239d5d2b)

Solutions

1. Branch on scheme first: only call file_uri_to_path when uri.startswith('file:')
2. Use convert_uri() instead of the helper — it performs the routing for you
3. Validate with urlparse(uri).scheme == 'file' before calling

Example fix

# before
file_uri_to_path("https://example.com/a.txt")  # ValueError

# after
from urllib.parse import urlparse
if urlparse(uri).scheme == "file":
    netloc, path = file_uri_to_path(uri)

from urllib.parse import urlparse

assert urlparse(uri).scheme == "file"

from markitdown._uri_utils import file_uri_to_path

try:
    netloc, path = file_uri_to_path(uri)
except ValueError:
    # not a file URI; route to the appropriate handler
    raise

When it happens

Trigger: Directly calling markitdown._uri_utils.file_uri_to_path('https://x/f.txt') or ('data:text/plain,hi') — i.e. passing a non-file URI to a function dedicated to file URIs.

Common situations: Reusing the internal helper in custom pipelines that route URIs by scheme, or calling it on unvalidated user input containing http/data/scheme-less strings.

Related errors

• Unsupported file URI: {uri}. Netloc must be empty or localho
• Unsupported URI scheme: {uri.split(':')[0]}. Supported schem
• 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/56703039c540dc08. Report an issue: GitHub.