reflex-dev/reflex · error · FileNotFoundError

File not found: {src_file_local}

Error message

File not found: {src_file_local}

What it means

Raised by rx.asset() when the given local asset path does not exist on disk relative to the working directory (cwd / assets / path). Reflex requires local assets to physically exist so it can copy/symlink and version them into the app's assets directory. The check is skipped only when backend_only is true.

Source

Thrown at reflex/assets.py:260

        for use as a build-time module reference.

    Raises:
        FileNotFoundError: If the file does not exist.
        ValueError: If subfolder is provided for local assets.
    """
    assets = constants.Dirs.APP_ASSETS
    backend_only = EnvironmentVariables.REFLEX_BACKEND_ONLY.get()

    # Local asset handling
    if not shared:
        cwd = Path.cwd()
        src_file_local = cwd / assets / path
        if subfolder is not None:
            msg = "Subfolder is not supported for local assets."
            raise ValueError(msg)
        if not backend_only and not src_file_local.exists():
            msg = f"File not found: {src_file_local}"
            raise FileNotFoundError(msg)
        relative_path = f"/{path}"
        if backend_only and not src_file_local.exists():
            return AssetPathStr(relative_path)
        return _versioned_asset_path(relative_path, src_file_local)

    # Shared asset handling
    # Determine the file by which the asset is exposed.
    frame = inspect.stack()[_stack_level]
    calling_file = frame.filename
    module = inspect.getmodule(frame[0])
    assert module is not None

    external = constants.Dirs.EXTERNAL_APP_ASSETS
    src_file_shared = Path(calling_file).parent / path
    if not src_file_shared.exists():
        msg = f"File not found: {src_file_shared}"
        raise FileNotFoundError(msg)

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Verify the file exists at the printed path and fix the typo or case in rx.asset(...)
2. If the asset lives in another package, use the shared-asset syntax rx.asset('/@pkg:pkgname/style.css') or put the file under your app's assets directory
3. Ensure the process cwd is the project root (or pass a path valid from the current cwd)
4. If you intentionally reference a backend-only file that may not exist yet, pass backend_only=True and handle the returned unversioned path

Example fix

// before
rx.image(src=rx.asset("/logo.png"))  # FileNotFoundError: File not found: .../assets/logo.png
// after
rx.image(src=rx.asset("/logo.png"))  # after adding logo.png to <project>/assets/

from pathlib import Path

def safe_asset(path: str, **kwargs):
    import reflex as rx
    if not path.startswith(("http://", "https://", "/@pkg:")):
        local = Path.cwd() / ".web" / "assets" / path.lstrip("/")
        if not local.exists():
            raise FileNotFoundError(f"missing asset: {local}")
    return rx.asset(path, **kwargs)

try:
    src = rx.asset("/logo.png")
except FileNotFoundError as e:
    log.warning(f"asset missing, falling back: {e}")
    src = "/favicon.ico"

When it happens

Trigger: Calling rx.asset('/myfile.png') (or a path without leading slash) where no such file exists under <project>/.web/assets (or the configured assets dir). Happens for local paths only, since http(s):// URLs and shared (@pkg:style) paths take other branches. Also raised when the working directory during import is not the project root, making the resolved relative path wrong.

Common situations: Typos in the asset path; asset file not committed/pulled with the repo (gitignore excludes); running the app from a different cwd so relative resolution fails; case-sensitivity mismatch of the filename (developed on macOS/Linux, deployed on a case-sensitive fs or vice versa).

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• File not found: {src_file_shared}
• The stylesheet file {stylesheet_full_path} does not exist.
• ChildrenTypeError(component=cls.__name__, child=child)
• Do not override _add_style directly. Use add_style instead.
• The component `{comp_name}` cannot have `{child_name}` as a

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