{"record":{"id":"220985017b954d1c","repo":"odysseus-dev/odysseus","slug":"this-mlx-image-pipeline-requires-a-companion-visio","errorCode":null,"errorMessage":"This MLX image pipeline requires a companion vision-language model. Relaunch with --vlm-model <repo_or_path> or set ODYSSEUS_MLX_IMAGE_VLM_MODEL.","messagePattern":"This MLX image pipeline requires a companion vision-language model\\. Relaunch with --vlm-model <repo_or_path> or set ODYSSEUS_MLX_IMAGE_VLM_MODEL\\.","errorType":"http","errorClass":"HTTPException","httpStatus":422,"severity":"error","filePath":"scripts/mlx_image_server.py","lineNumber":301,"sourceCode":"        detail = (proc.stderr or proc.stdout or \"HiDream generator failed\").strip()\n        raise HTTPException(500, detail[-4000:])\n\n\ndef _generate_boogu(model: str, prompt: str, out_path: Path, width: int, height: int, steps: int) -> None:\n    try:\n        from boogu_image_mlx.pipeline_mlx import BooguImagePipeline\n        from PIL import Image\n    except Exception as e:\n        raise HTTPException(\n            503,\n            \"Boogu MLX serving requires boogu-image-mlx in the launch Python. \"\n            \"Install with: python -m pip install -U git+https://github.com/xocialize/boogu-image-mlx.git\",\n        ) from e\n\n    model_path = _snapshot_path(model)\n    vlm_model = (_args.vlm_model or os.environ.get(\"ODYSSEUS_MLX_IMAGE_VLM_MODEL\") or \"\").strip()\n    if not vlm_model:\n        raise HTTPException(\n            422,\n            \"This MLX image pipeline requires a companion vision-language model. \"\n            \"Relaunch with --vlm-model <repo_or_path> or set ODYSSEUS_MLX_IMAGE_VLM_MODEL.\",\n        )\n    try:\n        pipe = BooguImagePipeline.from_pretrained(\n            str(model_path),\n            vlm_model,\n        )\n        img = pipe.generate(\n            prompt,\n            height=height,\n            width=width,\n            steps=steps,\n            guidance=3.5,\n        )\n        Image.fromarray(img).save(out_path)\n    except Exception as e:","sourceCodeStart":283,"sourceCodeEnd":319,"githubUrl":"https://github.com/odysseus-dev/odysseus/blob/f9235ebbf13f693a6fd29ce70b097f6ec83705bf/scripts/mlx_image_server.py#L283-L319","documentation":"Raised by _generate_boogu in scripts/mlx_image_server.py with HTTP 422 when no companion vision-language model is configured. BooguImagePipeline.from_pretrained takes (model_path, vlm_model): the VLM is architecturally required for prompt encoding, so generation is refused before loading weights.","triggerScenarios":"Generating with a Boogu model while both the --vlm-model CLI arg and the ODYSSEUS_MLX_IMAGE_VLM_MODEL env var are unset/empty/whitespace.","commonSituations":"Reusing an old launch command after upgrading to a Boogu-requiring version; env var set in one shell but the server launched from another (launchd, IDE runner); vlm_model value passed but empty string.","solutions":["Relaunch with --vlm-model <repo_or_path> (e.g. a Qwen2-VL MLX repo)","Or export ODYSSEUS_MLX_IMAGE_VLM_MODEL=<repo_or_path> in the environment the server actually starts from","Verify with a print of os.environ inside the server if the var seems ignored"],"exampleFix":"# before\npython scripts/mlx_image_server.py --model xocialze/boogu-image\n# after\npython scripts/mlx_image_server.py --model xocialize/boogu-image --vlm-model Qwen/Qwen2.5-VL-7B-Instruct-MLX","handlingStrategy":"validation","validationCode":"import os\nvlm = os.environ.get('ODYSSEUS_MLX_IMAGE_VLM_MODEL', '').strip()\nassert vlm, 'set ODYSSEUS_MLX_IMAGE_VLM_MODEL or pass --vlm-model before serving boogu'","typeGuard":"def vlm_configured(args_vlm: str | None) -> bool:\n    return bool((args_vlm or os.environ.get('ODYSSEUS_MLX_IMAGE_VLM_MODEL') or '').strip())","tryCatchPattern":null,"preventionTips":["Put the VLM env var in the launch wrapper/systemd unit, not the interactive shell","Fail fast at startup when the model is boogu and no VLM is set","Keep model->companion-VLM pairs in a config map"],"tags":["boogu","mlx","configuration","http-422"],"backgroundTag":null,"analyzedSha":"f9235ebbf13f693a6fd29ce70b097f6ec83705bf","analyzedAt":"2026-08-14T21:47:48.359Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}