reflex-dev/reflex · error · FileNotFoundError

File not found: {src_file_shared}

Error message

File not found: {src_file_shared}

What it means

Raised by rx.asset() for shared assets (@pkg:...) when the file cannot be found relative to the calling module's file (Path(calling_file).parent / path). Reflex resolves shared assets from the source module's directory so they can be symlinked into the app's external assets directory; a missing file aborts that.

Source

Thrown at reflex/assets.py:277

            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)

    caller_module_path = module.__name__.replace(".", "/")
    subfolder = f"{caller_module_path}/{subfolder}" if subfolder else caller_module_path

    # Symlink the asset to the app's external assets directory if running frontend.
    if not backend_only:
        # Create the asset folder in the currently compiling app.
        asset_folder = Path.cwd() / assets / external / subfolder
        asset_folder.mkdir(parents=True, exist_ok=True)

        dst_file = asset_folder / path

        if not dst_file.exists() and (
            not dst_file.is_symlink() or dst_file.resolve() != src_file_shared.resolve()
        ):
            try:
                dst_file.symlink_to(src_file_shared)
            except FileExistsError:

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Check the installed package on disk (site-packages) to confirm the actual asset path and correct the rx.asset call
2. Pin or upgrade/downgrade the component package to a version that ships the file at the path you reference
3. If the asset is yours, move it next to the calling module or reference it as a local asset instead
4. Reinstall the package if its data files were excluded from the wheel

Example fix

// before
rx.color_mode.button(style=rx.asset("/@pkg:my_lib/button.css"))
// after
rx.color_mode.button(style=rx.asset("/@pkg:my_lib/styles/button.css"))  # actual shipped path

from pathlib import Path
import reflex as rx

def shared_asset(pkg_path: str) -> str:
    # pkg_path like '/@pkg:somepkg/file.css'
    _, spec = pkg_path.split(":", 1)
    mod, _, rel = spec.partition("/")
    import importlib, reflex as _rx
    base = Path(importlib.import_module(mod).__file__).parent
    if not (base / rel).exists():
        raise FileNotFoundError(f"{pkg_path} not shipped by {mod}")
    return rx.asset(pkg_path)

try:
    href = rx.asset("/@pkg:my_lib/button.css")
except FileNotFoundError:
    href = rx.asset("/button.css")  # local fallback

When it happens

Trigger: Using rx.asset('/@pkg:somepkg/path/file.css') where somepkg does not actually ship that file at that path, or where the calling module's __file__ location makes the joined path wrong. Triggered during page render / app creation when favicons_links or index call into asset().

Common situations: Upgrading a component library whose asset layout changed (path moved/renamed); typo in the @pkg: sub-path; package installed without its data files (broken wheel or MANIFEST exclusion); namespace/relative import edge cases where calling_file resolution is off.

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_local}
• 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
• The component `{comp_name}` only allows the components: {val

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