{"record":{"id":"845e42d91444dd73","repo":"NousResearch/hermes-agent","slug":"image-backend-sprite-name-cannot-use-reference","errorCode":null,"errorMessage":"image backend '{sprite.name}' cannot use reference images; configure OpenAI gpt-image-2 or Krea for pet generation","messagePattern":"image backend '(.+?)' cannot use reference images; configure OpenAI gpt-image-2 or Krea for pet generation","errorType":"exception","errorClass":"GenerationError","httpStatus":null,"severity":"error","filePath":"agent/pet/generate/imagegen.py","lineNumber":204,"sourceCode":"    reference_images: list[Path] | None = None,\n    provider: SpriteProvider | None = None,\n    prefix: str = \"pet_gen\",\n    aspect_ratio: str = \"square\",\n) -> list[Path]:\n    \"\"\"Generate *n* sprite images and return their local paths.\n\n    *reference_images* grounds the output on a base image (required for rows).\n    *aspect_ratio* picks the canvas: ``\"square\"`` for single-character base\n    drafts, ``\"landscape\"`` for multi-frame row strips (the wider 1536px canvas\n    gives every frame real horizontal room so winged poses don't have to be\n    shrunk to avoid touching their neighbors).\n    We *ask* for a transparent background, but fall back to an opaque generation\n    (cleaned up downstream by the chroma-key pass) on models that reject the\n    flag. Raises :class:`GenerationError` if nothing usable comes back.\n    \"\"\"\n    sprite = provider or resolve_provider(require_references=bool(reference_images))\n    if reference_images and not sprite.supports_references:\n        raise GenerationError(\n            f\"image backend '{sprite.name}' cannot use reference images; \"\n            \"configure OpenAI gpt-image-2 or Krea for pet generation\"\n        )\n\n    refs = [str(p) for p in (reference_images or [])]\n\n    def _run(extra: dict) -> tuple[Path | None, str]:\n        kwargs: dict = {\"aspect_ratio\": aspect_ratio, **extra}\n        if refs:\n            # Providers disagree on the ref kwarg name: our OpenRouter/Nous\n            # backends read ``reference_images``, OpenAI's gpt-image-2 reads\n            # ``reference_image_urls``. Send both; each ignores the other.\n            kwargs[\"reference_images\"] = refs\n            kwargs[\"reference_image_urls\"] = refs\n        try:\n            result = sprite.provider.generate(prompt, **kwargs)\n        except Exception as exc:  # noqa: BLE001 - normalize provider crashes\n            logger.debug(\"provider.generate crashed: %s\", exc)","sourceCodeStart":186,"sourceCodeEnd":222,"githubUrl":"https://github.com/NousResearch/hermes-agent/blob/c896c09c42910c584c4c7d2325b58c14713ea42c/agent/pet/generate/imagegen.py#L186-L222","documentation":"Error \"image backend '{sprite.name}' cannot use reference images; configure OpenAI gpt-image-2 or Krea for pet generation\" thrown in NousResearch/hermes-agent.","triggerScenarios":"Thrown at agent/pet/generate/imagegen.py:204 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Switch the image backend to OpenAI gpt-image-2 or Krea, which support reference images.","Remove the reference image and use a backend that generates from text only."],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"c896c09c42910c584c4c7d2325b58c14713ea42c","analyzedAt":"2026-08-14T17:18:01.089Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}