Bug

LoRA training via mlx_vlm.lora crashes when saving checkpoints because args.adapter_file is None.

Error

File "mlx_vlm/trainer/sft_trainer.py", line 471, in train
    save_adapter(model, args.adapter_file)
File "mlx_vlm/trainer/utils.py", line 235, in save_adapter
    path = Path(adapter_file)
TypeError: argument should be a str or an os.PathLike object where __fspath__ returns a str, not 'NoneType'

This happens at:

• Line 471: checkpoint save (steps_per_save)
• Line 473: checkpoint filename generation
• Line 484: final weights save

Root Cause

When calling main(args) with a SimpleNamespace, even if adapter_file is set, the internal TrainingArgs object doesn't always propagate it. The adapter_file field ends up as None when the save function is called.

Reproduction

import types
from mlx_vlm.lora import main

args = types.SimpleNamespace(
    model_path='mlx-community/gemma-4-26b-a4b-it-4bit',
    dataset='./data/',
    adapter_path='./adapters/',
    adapter_file='./adapters/adapters.safetensors',
    # ... other args
)
main(args)  # Crashes at checkpoint save

Suggested Fix

In sft_trainer.py, add a fallback for adapter_file at lines 471, 473, and 484:

adapter_file = args.adapter_file or str(Path(getattr(args, 'adapter_path', '/tmp')) / "adapters.safetensors")
save_adapter(model, adapter_file)

This ensures save always has a valid path, falling back to the adapter_path directory.

Environment

• mlx-vlm 0.4.3
• macOS 26, Apple M5 Max 128GB
• Training Gemma 4 26B-A4B with LoRA