What causes "Cannot resolve image: {type(image_data)}" in unslothai/unsloth?

Inspect sample[image_column] types across the dataset (df['image'].map(type).value_counts()) to find the unexpected shape.

unslothai/unsloth · error · ValueError

Cannot resolve image: {type(image_data)}

Error message

Cannot resolve image: {type(image_data)}

What it means

Raised by the internal _resolve_image helper during ShareGPT+image conversion when a sample's image value matches none of the supported shapes. Supported inputs are: a string path/URL (including HF hub repo refs resolved via cache), or a dict with 'bytes' or 'path' keys. Anything else (int, float, list, None, dict without those keys) hits the terminal ValueError with the offending type name.

Source

Thrown at studio/backend/utils/datasets/format_conversion.py:816

                from huggingface_hub import hf_hub_download
                from utils.hf_cache_settings import active_hf_hub_cache

                local_path = hf_hub_download(
                    dataset_name,
                    _image_lookup[image_data],
                    repo_type = "dataset",
                    cache_dir = active_hf_hub_cache(),
                )
                return Image.open(local_path).convert("RGB")
            else:
                return Image.open(image_data).convert("RGB")
        if isinstance(image_data, dict) and ("bytes" in image_data or "path" in image_data):
            if image_data.get("bytes"):
                from io import BytesIO
                return Image.open(BytesIO(image_data["bytes"])).convert("RGB")
            if image_data.get("path"):
                return Image.open(image_data["path"]).convert("RGB")
        raise ValueError(f"Cannot resolve image: {type(image_data)}")

    def _convert_single_sample(sample):
        """Convert one ShareGPT+image sample to standard VLM format."""
        pil_image = _resolve_image(sample[image_column])
        conversation = sample[messages_column]

        new_messages = []
        for msg in conversation:
            role_raw = msg.get("from") or msg.get("role", "user")
            role = _ROLE_MAP.get(role_raw.lower(), role_raw.lower())
            text = msg.get("value") or msg.get("content") or ""

            # Interleave text and image blocks around <image>
            if "<image>" in text:
                parts = text.split("<image>")
                content = []
                for i, part in enumerate(parts):
                    part = part.strip()

View on GitHub (pinned to 203007d190)

Solutions

Inspect sample[image_column] types across the dataset (df['image'].map(type).value_counts()) to find the unexpected shape.
Pre-map unsupported dicts to supported ones, e.g. {'url': x} -> {'path': x} or download bytes into 'bytes'.
Drop rows with None/invalid image values before conversion.
If the column is actually labels/boxes, pick the correct image column for conversion.
For dict-based HF image features, ensure the dataset was loaded with the image feature intact (not decoded to raw dicts by a transform).

Example fix

# before
# image column contains {'url': 'https://...'} -> ValueError: Cannot resolve image: <class 'dict'>

# after
ds = ds.map(lambda r: {"image": {"path": r["image"]["url"]}})
converted = convert_sharegpt_images(ds)

Defensive patterns

Strategy: type-guard

Validate before calling

from collections import Counter

def audit_image_column(ds, image_column):
    """Report value types in the image column before ShareGPT conversion."""
    return Counter(type(r).__name__ for r in ds[image_column])

# only proceed when audit shows dict/str only:
# audit_image_column(ds, 'images') -> {'dict': 1000} is fine; {'int': 500} is not

Type guard

def is_supported_image_value(value) -> bool:
    """Mirror _resolve_image's supported shapes."""
    if isinstance(value, str) and value:
        return True
    if isinstance(value, dict) and ("bytes" in value or "path" in value):
        return bool(value.get("bytes") or value.get("path"))
    return False

Try / catch

converted = []
for sample in ds:
    if is_supported_image_value(sample[image_column]):
        converted.append(_convert_single_sample(sample))  # skip unsupported rows
# then handle empty `converted` explicitly

Prevention

Type-audit the image column (str or {'bytes'/'path'} dict) before conversion.
Pre-normalize non-HF dict encodings like {'url': ...} to {'path': ...}.
Filter null image rows with ds.filter(lambda r: r[image_column] is not None).
Freeze dataset revisions so schema drift cannot silently change image encodings.

When it happens

Trigger: The image column of a ShareGPT-format dataset contains values like None, integers (class IDs), lists (bounding boxes), or dicts whose keys are neither 'bytes' nor 'path' (e.g. {'url': ...} or {'image': ...}).

Common situations: Loading a classification dataset (label column instead of image), a detection dataset with list annotations, or datasets using non-HF image encodings such as {'url': ...} raw dicts; schema drift after a dataset revision changed the image column format.

Related errors

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/0c4c97b9f1e77c5b. Report an issue: GitHub.