roboflow/supervision · error · ValueError

Invalid asset. It should be one of the following

Error message

Invalid asset. It should be one of the following: {valid_assets}.

What it means

Raised by download_assets() when asset_name is neither a member of the Assets enum nor a key of the MEDIA_ASSETS dictionary. The downloader can only fetch assets it knows the URL and MD5 for, so unknown names are rejected up front with the list of valid options.

Solutions

Use the enum: from supervision.assets import Assets; download_assets(Assets.ENCODED_VIDEO, directory=...).
If you only have a string, pass the exact key from MEDIA_ASSETS — print supervision.assets.downloader.MEDIA_ASSETS.keys() to see valid names.
Check the installed supervision version's Assets members if the name came from newer/older docs.

Example fix

// before
path = download_assets("cctv-1080p.mp4")

// after
from supervision.assets import Assets
path = download_assets(Assets.ENCODED_VIDEO, directory="assets")

Defensive patterns

Strategy: validation

Validate before calling

from supervision.assets import Assets, downloader
valid = {a.value for a in Assets} | set(downloader.MEDIA_ASSETS)
if isinstance(asset_name, str) and asset_name not in valid:
    raise ValueError(f"Unknown asset {asset_name!r}; valid: {sorted(valid)}")
path = download_assets(asset_name, directory=directory)

Type guard

def is_valid_asset(name) -> bool:
    from supervision.assets import Assets, downloader
    return name in {a.value for a in Assets} | set(downloader.MEDIA_ASSETS)

Prevention

Always use the Assets enum, never raw filenames.
If dependent on docs examples, verify the enum member exists in your installed supervision version.
Print Assets members after upgrading supervision.

When it happens

Trigger: Calling download_assets("video.mp4") with a raw filename instead of Assets.ENCODED_VIDEO, or passing a typo like Assets.VIDEO, or an asset name string that was never registered in MEDIA_ASSETS.

Common situations: Copy-pasting asset filenames from docs/issues instead of the enum; supervision versions where the Assets enum gained/renamed members; user code written against a different fork with extra assets.

Related errors

AI-assisted analysis of roboflow/supervision@7f254d9784 (2026-08-15). Data as JSON: /api/errors/9335e718c33bb269. Report an issue: GitHub.

Appendix: source

Thrown at src/supervision/assets/downloader.py:137

                original_md5_hash=original_md5_hash,
                destination=destination,
                check_target=check_target,
            )
        else:
            if not is_md5_hash_matching(check_target, original_md5_hash):
                logger.warning("File corrupted. Re-downloading...")
                os.remove(check_target)
                _download_verified_asset(
                    filename=filename,
                    original_md5_hash=original_md5_hash,
                    destination=destination,
                    check_target=check_target,
                )

            logger.info("%s asset download complete.", filename)
    else:
        valid_assets = ", ".join(filename for filename in MEDIA_ASSETS.keys())
        raise ValueError(
            f"Invalid asset. It should be one of the following: {valid_assets}."
        )

    return return_value

View on GitHub (pinned to 7f254d9784)