{"record":{"id":"4e0790febfed8a04","repo":"odysseus-dev/odysseus","slug":"cli-not-found-in-path-or-next-to-sys-executable","errorCode":null,"errorMessage":"{cli} not found in PATH or next to {sys.executable}. Install the MLX image runtime with: python3 -m pip install -U mflux","messagePattern":"(.+?) not found in PATH or next to (.+?)\\. Install the MLX image runtime with: python3 -m pip install -U mflux","errorType":"http","errorClass":"HTTPException","httpStatus":503,"severity":"error","filePath":"scripts/mlx_image_server.py","lineNumber":347,"sourceCode":"def generate(req: ImageRequest):\n    model = req.model or _args.model\n    width, height = _size(req.size)\n    out_images = []\n    count = max(1, min(int(req.n or 1), 4))\n    for _ in range(count):\n        with tempfile.TemporaryDirectory(prefix=\"odysseus-mlx-image-\") as td:\n            out_path = Path(td) / \"image.png\"\n            if _is_hidream(model):\n                _generate_hidream(model, req.prompt, out_path, width, height, _steps(req.quality))\n            elif _is_boogu(model):\n                _generate_boogu(model, req.prompt, out_path, width, height, _steps(req.quality))\n            elif _is_lama_inpaint(model) or _is_ddcolor(model):\n                raise _unsupported_swift_mlx_runtime(model)\n            else:\n                cli = _cli_for_model(model)\n                cli_path = _resolve_cli(cli)\n                if not cli_path:\n                    raise HTTPException(\n                        503,\n                        f\"{cli} not found in PATH or next to {sys.executable}. Install the MLX image runtime with: python3 -m pip install -U mflux\",\n                    )\n                cmd = [\n                    cli_path,\n                    \"--model\",\n                    model,\n                    \"--prompt\",\n                    req.prompt,\n                    \"--steps\",\n                    str(_steps(req.quality)),\n                    \"--output\",\n                    str(out_path),\n                ]\n                if _args.base_model:\n                    cmd += [\"--base-model\", _args.base_model]\n                if _args.lora_style:\n                    cmd += [\"--lora-style\", _args.lora_style]","sourceCodeStart":329,"sourceCodeEnd":365,"githubUrl":"https://github.com/odysseus-dev/odysseus/blob/f9235ebbf13f693a6fd29ce70b097f6ec83705bf/scripts/mlx_image_server.py#L329-L365","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install mflux into the launch interpreter: python3 -m pip install -U mflux (use the same python that runs the server)","Check the CLI resolves from that environment: <python> -m pip show mflux and ls <sys.executable dir>/flux","If installed elsewhere, either activate that venv before launching the server or add its bin dir to PATH"],"exampleFix":"# before\n/usr/bin/python3 scripts/mlx_image_server.py --model flux-schnell  # 503\n# after\nsource .venv/bin/activate && pip install -U mflux\npython scripts/mlx_image_server.py --model flux-schnell","handlingStrategy":"type-guard","validationCode":"import shutil, sys, pathlib\ncli = 'flux'\ncandidates = [shutil.which(cli), pathlib.Path(sys.executable).parent / cli]\nassert any(c and pathlib.Path(c).exists() for c in candidates), 'pip install -U mflux'","typeGuard":"def mflux_cli_available(cli: str) -> bool:\n    import shutil, pathlib, sys\n    p = shutil.which(cli) or pathlib.Path(sys.executable).parent / cli\n    return bool(p) and pathlib.Path(p).exists()","tryCatchPattern":null,"preventionTips":["Install mflux into the same venv that launches the server","Add a startup self-test that resolves the CLI for every configured model","Launch via the venv's python, not system python"],"tags":["mflux","mlx","dependency","cli","http-503"],"backgroundTag":null,"analyzedSha":"f9235ebbf13f693a6fd29ce70b097f6ec83705bf","analyzedAt":"2026-08-14T21:47:48.359Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}