odysseus-dev/odysseus · error · HTTPException

{cli} not found in PATH or next to {sys.executable}. Install

Error message

{cli} not found in PATH or next to {sys.executable}. Install the MLX image runtime with: python3 -m pip install -U mflux

What it means

Raised in the /v1/images/generations handler of scripts/mlx_image_server.py with HTTP 503 when the mflux CLI (e.g. 'flux', 'flux-fill', or whatever _cli_for_model returns) is neither on PATH nor next to sys.executable. The default generation path shells out to that CLI, so the mflux package must be installed in the server's environment.

Source

Thrown at scripts/mlx_image_server.py:347

def generate(req: ImageRequest):
    model = req.model or _args.model
    width, height = _size(req.size)
    out_images = []
    count = max(1, min(int(req.n or 1), 4))
    for _ in range(count):
        with tempfile.TemporaryDirectory(prefix="odysseus-mlx-image-") as td:
            out_path = Path(td) / "image.png"
            if _is_hidream(model):
                _generate_hidream(model, req.prompt, out_path, width, height, _steps(req.quality))
            elif _is_boogu(model):
                _generate_boogu(model, req.prompt, out_path, width, height, _steps(req.quality))
            elif _is_lama_inpaint(model) or _is_ddcolor(model):
                raise _unsupported_swift_mlx_runtime(model)
            else:
                cli = _cli_for_model(model)
                cli_path = _resolve_cli(cli)
                if not cli_path:
                    raise HTTPException(
                        503,
                        f"{cli} not found in PATH or next to {sys.executable}. Install the MLX image runtime with: python3 -m pip install -U mflux",
                    )
                cmd = [
                    cli_path,
                    "--model",
                    model,
                    "--prompt",
                    req.prompt,
                    "--steps",
                    str(_steps(req.quality)),
                    "--output",
                    str(out_path),
                ]
                if _args.base_model:
                    cmd += ["--base-model", _args.base_model]
                if _args.lora_style:
                    cmd += ["--lora-style", _args.lora_style]

View on GitHub (pinned to f9235ebbf1)

Solutions

1. Install mflux into the launch interpreter: python3 -m pip install -U mflux (use the same python that runs the server)
2. Check the CLI resolves from that environment: <python> -m pip show mflux and ls <sys.executable dir>/flux
3. If installed elsewhere, either activate that venv before launching the server or add its bin dir to PATH

Example fix

# before
/usr/bin/python3 scripts/mlx_image_server.py --model flux-schnell  # 503
# after
source .venv/bin/activate && pip install -U mflux
python scripts/mlx_image_server.py --model flux-schnell

import shutil, sys, pathlib
cli = 'flux'
candidates = [shutil.which(cli), pathlib.Path(sys.executable).parent / cli]
assert any(c and pathlib.Path(c).exists() for c in candidates), 'pip install -U mflux'

def mflux_cli_available(cli: str) -> bool:
    import shutil, pathlib, sys
    p = shutil.which(cli) or pathlib.Path(sys.executable).parent / cli
    return bool(p) and pathlib.Path(p).exists()

When it happens

Trigger: POST /v1/images/generations with a non-HiDream/non-Boogu/non-LaMa/non-DDColor model (i.e. FLUX via mflux) when shutil.which and the python-bin directory search both fail to locate the CLI executable.

Common situations: mflux installed in a venv but server launched with system python (or vice versa); mflux installed with --user so the CLI lands outside PATH; pipx install puts the CLI in a separate environment; fresh machine where only the server package was installed.

Related errors

• huggingface_hub is required to download MLX image model snap
• Pillow is required for MLX image edit bridge inputs.
• Pillow is required for MLX image edit bridge masks.
• Boogu MLX serving requires boogu-image-mlx in the launch Pyt
• Memory store is temporarily unreadable — nothing was importe

AI-assisted analysis of odysseus-dev/odysseus@f9235ebbf1 (2026-08-14). Data as JSON: /api/errors/4e0790febfed8a04. Report an issue: GitHub.