[misc] improve diagnostics for missing processor on multi-modal templates

[gaurav0107]

Summary

Fixes #10539 (and helps several similar reports: #10447, #10193, #9385, #9182, #8780).

When a multi-modal template (e.g. qwen3_5, qwen3_vl, glm4v) is selected but AutoProcessor.from_pretrained fails or returns a non-Processor instance, model/loader.py silently sets processor = None. Later, mm_plugin._validate_input raises:

ValueError: Processor was not found, please check and update your model file.

This message gives users no idea what to do. The actual root cause is almost always one of:

• An incomplete HF cache (e.g. missing preprocessor_config.json),
• A transformers version that does not yet support the model's processor class, or
• The wrong template choice (a multi-modal template selected for text-only fine-tuning).

Changes

• src/llamafactory/model/loader.py
  • Promote info_rank0 -> warning_rank0 for the silent processor-load failure so users actually see the underlying exception.
  • Log a warning (instead of debug) when a loaded processor is dropped because its class name does not contain "Processor", including the dropped class name for diagnosis.
• src/llamafactory/data/mm_plugin.py
  • Replace the four generic "please check and update your model file." errors with actionable guidance: verify the model files are complete, upgrade transformers, or pick a text-only template if multi-modal inputs are not needed.

Behavior

• No change on the success path.
• Only diagnostic improvements in the failure path. No tests pin the prior message strings (verified by grep across tests/ and tests_v1/).

Verification

• uvx ruff check src/llamafactory/data/mm_plugin.py src/llamafactory/model/loader.py -> all checks passed
• uvx ruff format --check src/llamafactory/data/mm_plugin.py src/llamafactory/model/loader.py -> already formatted
• python3 tests/check_license.py scripts src tests tests_v1 -> exit 0

[gemini-code-assist]

Code Review

This pull request improves error messages and logging when multi-modal processors fail to load. In mm_plugin.py, ValueError messages are expanded with detailed troubleshooting steps, and in loader.py, loading failures and dropped processors are now logged as warnings with additional context. The review feedback highlights two key improvements: nesting the try-except blocks in loader.py to prevent unhandled exceptions from sibling except blocks, and expanding the processor check in mm_plugin.py to cover video and audio tokens as well as image tokens.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

In Python, an exception raised inside an except block (such as the except ValueError: block on lines 103-108) will not be caught by a sibling except Exception as e: block of the same try statement. If the second AutoProcessor.from_pretrained call fails, the exception will propagate and crash the application instead of being caught and logged with the new diagnostic warning.

To ensure all processor loading failures are gracefully caught and logged, the inner try/except ValueError should be nested inside an outer try/except Exception block.

[gaurav0107]

Good catch. Fixed in e19bce0 by nesting the inner except ValueError retry inside an outer try so any failure from the second AutoProcessor.from_pretrained call is now caught by the outer except Exception as e and logged via warning_rank0. Thanks for the review.

[gemini-code-assist]

If the model/template is video-only or audio-only (where self.image_token is None but self.video_token or self.audio_token is set) and the processor fails to load, this check will be skipped. The user will then receive a more specific (and potentially misleading) error message like Video processor was not found or Audio feature extractor was not found instead of the comprehensive diagnostic message for the missing processor.

Checking if any of the multi-modal tokens are expected when processor is None provides a much more robust and helpful diagnostic experience.

Suggested change

	if self.image_token is not None and processor is None:
	if (self.image_token is not None or self.video_token is not None or self.audio_token is not None) and processor is None:

[gaurav0107]

Good catch. Fixed in e19bce0 by checking all three modality tokens (image, video, audio). Video-only/audio-only templates with a missing processor will now surface the comprehensive diagnostic instead of the more specific sub-processor error. Thanks for the review.