reflex-dev/reflex · error · ValueError

The URL argument should start with a /

Error message

The URL argument should start with a /

What it means

rx.download() only supports internal/relative URLs for the url argument; string urls must begin with '/' so the framework can route the download through its server-side helper. External http(s) links are not accepted here.

Source

Thrown at packages/reflex-base/src/reflex_base/event/__init__.py:1732

    Args:
        url: The URL to the file to download.
        filename: The name that the file should be saved as after download.
        data: The data to download.
        mime_type: The mime type of the data to download.

    Returns:
        EventSpec: An event to download the associated file.

    Raises:
        ValueError: If the URL provided is invalid, both URL and data are provided,
            or the data is not an expected type.
    """
    from reflex_components_core.core.cond import cond

    if isinstance(url, str):
        if not url.startswith("/"):
            msg = "The URL argument should start with a /"
            raise ValueError(msg)

        # if filename is not provided, infer it from url
        if filename is None:
            filename = url.rpartition("/")[-1]

    if filename is None:
        filename = ""

    if data is not None:
        if url is not None:
            msg = "Cannot provide both URL and data to download."
            raise ValueError(msg)

        if isinstance(data, str):
            if mime_type is None:
                mime_type = "text/plain"
            # Caller provided a plain text string to download.
            url = f"data:{mime_type};base64," + b64encode(data.encode("utf-8")).decode(

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Prefix the path with '/' if it is an app-served file: rx.download('/report.pdf')
2. For external URLs, open them client-side instead (e.g. rx.redirect or an <a> link), or fetch the bytes and pass data= to rx.download
3. Ensure the file exists under assets/ so it is served at the root path

Example fix

# before
rx.download(url='report.pdf')
# after
rx.download(url='/report.pdf')

def valid_download_url(u: str | None) -> bool:
    return u is None or u.startswith('/')

def is_internal_url(u) -> TypeGuard[str]: return isinstance(u, str) and u.startswith('/')

When it happens

Trigger: Calling rx.download(url='https://example.com/file.pdf') or rx.download(url='files/report.pdf') with a string not starting with '/'.

Common situations: Trying to trigger a download of an external asset, or forgetting the leading slash on a static file served from the app's public directory.

Related errors

• Cannot provide both URL and data to download.
• Invalid data type {type(data)} for download. Use `str` or `b
• Failed to download the template: {he}
• ChildrenTypeError(component=cls.__name__, child=child)
• Do not override _add_style directly. Use add_style instead.

AI-assisted analysis of reflex-dev/reflex@45b8ed5ab7 (2026-08-28). Data as JSON: /api/errors/1a9a52953ce17add. Report an issue: GitHub.