NousResearch/hermes-agent · error · GenerationError

image backend '{sprite.name}' cannot use reference images; c

Error message

image backend '{sprite.name}' cannot use reference images; configure OpenAI gpt-image-2 or Krea for pet generation

What it means

Error "image backend '{sprite.name}' cannot use reference images; configure OpenAI gpt-image-2 or Krea for pet generation" thrown in NousResearch/hermes-agent.

Source

Thrown at agent/pet/generate/imagegen.py:204

    reference_images: list[Path] | None = None,
    provider: SpriteProvider | None = None,
    prefix: str = "pet_gen",
    aspect_ratio: str = "square",
) -> list[Path]:
    """Generate *n* sprite images and return their local paths.

    *reference_images* grounds the output on a base image (required for rows).
    *aspect_ratio* picks the canvas: ``"square"`` for single-character base
    drafts, ``"landscape"`` for multi-frame row strips (the wider 1536px canvas
    gives every frame real horizontal room so winged poses don't have to be
    shrunk to avoid touching their neighbors).
    We *ask* for a transparent background, but fall back to an opaque generation
    (cleaned up downstream by the chroma-key pass) on models that reject the
    flag. Raises :class:`GenerationError` if nothing usable comes back.
    """
    sprite = provider or resolve_provider(require_references=bool(reference_images))
    if reference_images and not sprite.supports_references:
        raise GenerationError(
            f"image backend '{sprite.name}' cannot use reference images; "
            "configure OpenAI gpt-image-2 or Krea for pet generation"
        )

    refs = [str(p) for p in (reference_images or [])]

    def _run(extra: dict) -> tuple[Path | None, str]:
        kwargs: dict = {"aspect_ratio": aspect_ratio, **extra}
        if refs:
            # Providers disagree on the ref kwarg name: our OpenRouter/Nous
            # backends read ``reference_images``, OpenAI's gpt-image-2 reads
            # ``reference_image_urls``. Send both; each ignores the other.
            kwargs["reference_images"] = refs
            kwargs["reference_image_urls"] = refs
        try:
            result = sprite.provider.generate(prompt, **kwargs)
        except Exception as exc:  # noqa: BLE001 - normalize provider crashes
            logger.debug("provider.generate crashed: %s", exc)

View on GitHub (pinned to c896c09c42)

Solutions

1. Switch the image backend to OpenAI gpt-image-2 or Krea, which support reference images.
2. Remove the reference image and use a backend that generates from text only.

When it happens

Trigger: Thrown at agent/pet/generate/imagegen.py:204 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/845e42d91444dd73. Report an issue: GitHub.