Skip to documentation
AgentDocksDocumentation

Troubleshooting

Reference ignored

The product came out different, the person changed, or the style you attached was not used. Work down this list; the cause is almost always one of the first four.

Last reviewed October 25, 2026

Check these in order

  1. 1

    Does this model take references at all?

    Only some models read reference pictures. If the composer or the node shows no reference strip for the selected model, the picture is not being sent. Switch to a model that declares references; the picker tells you which ones do and how many.
  2. 2

    Is the picture actually attached?

    In Studio the picture must be on the reference strip above the prompt, not only on the canvas. In the editor it must be uploaded inside the node or wired into Attachments, and the node's attachment strip must show it. A preview sitting next to a generator does nothing by itself.
  3. 3

    Are you over the model's limit?

    Each model accepts a fixed number of references. Beyond it, the run is refused with the number, and switching to a model with a lower limit keeps only what fits. Fewer, better references beat many.
  4. 4

    Does the prompt point at it?

    Some models read references by number: say which picture is the product and which is the style, as in the product in image 1 in the setting of image 2. And prompt the difference, not a re-description of the picture: the picture already carries the subject, so the words should carry what changes.
  5. 5

    Is the picture clean enough?

    A plain background, the product filling the frame and nothing else in shot gives the model the least to misread. Busy backgrounds and tiny products drift.
  6. 6

    Is the setting right for the job?

    A low quality tier or a small resolution loses label text and fine detail. For packaging, step up the quality and the size before blaming the reference.

Video has one extra rule

A video model takes its media in one shape at a time: a pool of references, a start frame, or a clip to edit. The active tab decides what is sent. A picture dropped into the References tab is a reference the prompt can name; the same picture in Start Frame is the first frame of the clip. If the result does not use the picture the way you expected, check which tab it is on.

Tools that fix the usual cases

The product must be exact
Cut it out first with Remove Background and use the cutout as the reference. Then describe only the scene around it.
The look is right but the product is wrong
Use Image to Prompt in product mode on the picture whose look you want. It writes a prompt for a scene your product will be placed into, and your product goes on the generator as the reference.
The person keeps changing
Generate the person once with Model Generator, then feed every later shot the same hero, or build a Character Sheet and reference that.
The set does not match
Keep the system fixed: the same references, the same prompt skeleton with only the subject changing, and Color Match against the hero shot afterwards.

A reference that ran through a free tool

If the picture reaches the generator through Crop & Resize, a color node or Painter, the baked result is what the model sees. That is usually what you want; if not, wire the original instead.
How references work on Image Generate