blaizzy/mlx-vlm/reproducible-github-issues

Reproducible GitHub Issues

Use this workflow to turn a failure into a concise, actionable MLX-VLM issue. Do not open a GitHub issue unless the user explicitly asks; otherwise produce issue-ready Markdown.

Required Information

Collect or infer:

• MLX-VLM version or git commit.
• Install method: PyPI, editable checkout, branch, or wheel.
• Python version, OS version, machine/chip, and whether MLX Metal or MLX CUDA is in use.
• Exact model ID or local path.
• Whether the model is from Hugging Face cache, a local conversion, or a custom checkpoint.
• Exact uv run CLI command or server startup command.
• Exact request body for server issues.
• Input media facts: image dimensions, audio duration/sample rate, video duration/frame count, and whether the input can be shared.
• Expected behavior, actual behavior, and full error/traceback.

Collect the Environment Automatically

Instead of hand-filling versions, run and paste the output into the Environment section:

uv run python - <<'PY'
import platform, mlx.core as mx
try:
    import mlx_vlm
    v = getattr(mlx_vlm, "__version__", "unknown")
except Exception as e:
    v = f"import failed: {e}"
print("mlx-vlm:", v)
print("mlx:", mx.__version__, "| default device:", mx.default_device())
print("python:", platform.python_version(), "| platform:", platform.platform())
PY

Repro Minimization

1. Reduce to the smallest command or request that still fails.
2. Remove private paths, tokens, and unrelated environment variables.
3. Prefer curl over client SDKs for server repros.
4. Prefer one image/audio/video file before multi-input repros.
5. Use small public media or synthetic inputs when possible.
6. State whether the bug reproduces with a public model or only a private/local checkpoint.

Issue Template

### Summary
 
<One sentence describing the failure.>
 
### Environment
 
- MLX-VLM:
- Python:
- OS:
- Hardware:
- Install method:
 
### Model
 
- Model:
- Source: <HF cache | local path | converted checkpoint>
- Trust remote code: <yes/no>
 
### Reproduction
 

uv run mlx_vlm.generate <args>

 
For server issues:
 

uv run mlx_vlm.server <args>

<curl request>

 
### Expected Behavior
 
<What should have happened.>
 
### Actual Behavior
 
<What happened instead.>
 
### Logs / Traceback
 

<trimmed traceback or relevant logs>

 
### Inputs
 
<Describe attached or shareable inputs. Include dimensions/duration when relevant.>

Classification

• CLI inference: use Skill("mlx-vlm-skills:cli-inference") if a repro command is still missing.
• Server inference: use Skill("mlx-vlm-skills:server-inference") if a minimal request is still missing.
• Model-specific failures: include config.json model_type, processor class, and whether the family has a README in mlx_vlm/models/.

Quality Bar

The issue is ready when a maintainer can run one command or one server command plus one request and see the same failure without asking for basic environment or model details.