Unity-Technologies/ml-agents · error · FileNotFoundError

Binary not found, make sure {url} is a valid url to a zip fo

Error message

Binary not found, make sure {url} is a valid url to a zip folder containing a valid Unity executable

What it means

FileNotFoundError raised by binary_utils.get_local_binary_path when, after attempting download/extraction from the given url, no matching Unity executable binary can be found locally for that (name, url) pair.

Source

Thrown at ml-agents-envs/mlagents_envs/registry/binary_utils.py:63

        for attempt in range(
            NUMBER_ATTEMPTS
        ):  # Perform 5 attempts at downloading the file
            if path is not None:
                break
            try:
                download_and_extract_zip(url, name, tmp_dir=tmp_dir)
            except Exception:
                if attempt + 1 < NUMBER_ATTEMPTS:
                    logger.warning(
                        f"Attempt {attempt + 1} / {NUMBER_ATTEMPTS}"
                        ": Failed to download and extract binary."
                    )
                else:
                    raise
            path = get_local_binary_path_if_exists(name, url, tmp_dir=tmp_dir)

    if path is None:
        raise FileNotFoundError(
            f"Binary not found, make sure {url} is a valid url to "
            "a zip folder containing a valid Unity executable"
        )
    return path


def get_local_binary_path_if_exists(name: str, url: str, tmp_dir: str) -> Optional[str]:
    """
    Recursively searches for a Unity executable in the extracted files folders. This is
    platform dependent : It will only return a Unity executable compatible with the
    computer's OS. If no executable is found, None will be returned.
    :param name: The name/identifier of the executable
    :param url: The url the executable was downloaded from (for verification)
    :param: tmp_dir: Optional override for the temporary directory to save binaries and zips in.
    """
    _, bin_dir = get_tmp_dirs(tmp_dir)
    extension = None

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Verify the url with curl -I; if dead, update the manifest to a valid zip containing the Unity executable.
2. Download the binary manually and place it in the expected cache path (bin_dir/name-<md5(url)>) or pass tmp_dir pointing at a pre-extracted location.
3. Check network/proxy settings and retry the download.
4. Use a local UnityEnvironment(file_name=...) directly instead of the remote registry.

Example fix

// before
entry = registry['3dball']  # url 404s at runtime
env = entry.make()
// after
env = UnityEnvironment(file_name='/path/to/3DBall/UnityEnvironment.x86_64')

import os, glob
path = os.path.join(tmp_dir, "**", "*.x86_64")  # match platform ext
if not glob.glob(path, recursive=True) and not os.environ.get("MLAGENTS_BINARY"):
    raise FileNotFoundError("Binary not downloaded yet; pre-fetch or set MLAGENTS_BINARY")
env = entry.make()

def binary_available(tmp_dir: str, name: str, url: str) -> bool:
    import hashlib, glob
    h = "-" + hashlib.md5(url.encode()).hexdigest()
    return len(glob.glob(os.path.join(tmp_dir, name + h, "**", "*"), recursive=True)) > 0

try:
    env = entry.make()
except FileNotFoundError:
    env = UnityEnvironment(file_name=os.environ["LOCAL_UNITY_BINARY"])

When it happens

Trigger: Calling a remote registry entry's make() (or get_local_binary_path directly) where the url points to a zip that failed to download, is invalid, has no executable inside, or whose cache directory in tmp_dir lacks a matching binary.

Common situations: Dead or moved binary-download URL; network blocked in CI so the zip never downloads; extracted zip uses an unexpected directory layout so the glob for the platform extension finds nothing; disk cache cleared between download and lookup.

Related errors

• The entry {self.identifier} does not contain a valid url for
• Couldn't launch the {file_name} environment. Provided filena
• The make() method not implemented for entry {self.identifier
• No extensions found for this platform.
• The entry {identifier} is not present in the registry.

AI-assisted analysis of Unity-Technologies/ml-agents@3ecb446f75 (2026-09-02). Data as JSON: /api/errors/a04ecea03c62394d. Report an issue: GitHub.