odysseus-dev/odysseus · error · HTTPException

This MLX image pipeline requires a companion vision-language

Error message

This MLX image pipeline requires a companion vision-language model. Relaunch with --vlm-model <repo_or_path> or set ODYSSEUS_MLX_IMAGE_VLM_MODEL.

What it means

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.

Source

Thrown at scripts/mlx_image_server.py:301

        detail = (proc.stderr or proc.stdout or "HiDream generator failed").strip()
        raise HTTPException(500, detail[-4000:])


def _generate_boogu(model: str, prompt: str, out_path: Path, width: int, height: int, steps: int) -> None:
    try:
        from boogu_image_mlx.pipeline_mlx import BooguImagePipeline
        from PIL import Image
    except Exception as e:
        raise HTTPException(
            503,
            "Boogu MLX serving requires boogu-image-mlx in the launch Python. "
            "Install with: python -m pip install -U git+https://github.com/xocialize/boogu-image-mlx.git",
        ) from e

    model_path = _snapshot_path(model)
    vlm_model = (_args.vlm_model or os.environ.get("ODYSSEUS_MLX_IMAGE_VLM_MODEL") or "").strip()
    if not vlm_model:
        raise HTTPException(
            422,
            "This MLX image pipeline requires a companion vision-language model. "
            "Relaunch with --vlm-model <repo_or_path> or set ODYSSEUS_MLX_IMAGE_VLM_MODEL.",
        )
    try:
        pipe = BooguImagePipeline.from_pretrained(
            str(model_path),
            vlm_model,
        )
        img = pipe.generate(
            prompt,
            height=height,
            width=width,
            steps=steps,
            guidance=3.5,
        )
        Image.fromarray(img).save(out_path)
    except Exception as e:

View on GitHub (pinned to f9235ebbf1)

Solutions

1. Relaunch with --vlm-model <repo_or_path> (e.g. a Qwen2-VL MLX repo)
2. Or export ODYSSEUS_MLX_IMAGE_VLM_MODEL=<repo_or_path> in the environment the server actually starts from
3. Verify with a print of os.environ inside the server if the var seems ignored

Example fix

# before
python scripts/mlx_image_server.py --model xocialze/boogu-image
# after
python scripts/mlx_image_server.py --model xocialize/boogu-image --vlm-model Qwen/Qwen2.5-VL-7B-Instruct-MLX

import os
vlm = os.environ.get('ODYSSEUS_MLX_IMAGE_VLM_MODEL', '').strip()
assert vlm, 'set ODYSSEUS_MLX_IMAGE_VLM_MODEL or pass --vlm-model before serving boogu'

def vlm_configured(args_vlm: str | None) -> bool:
    return bool((args_vlm or os.environ.get('ODYSSEUS_MLX_IMAGE_VLM_MODEL') or '').strip())

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• LaMa / MI-GAN inpainting requires an image mask. Use the edi
• Boogu MLX serving requires boogu-image-mlx in the launch Pyt
• Boogu MLX generation failed: {e}
• This MLX image endpoint supports text-to-image generation on
• HTTP ${res.status}${body ? ': ' + body.slice(0, 160) : ''}

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