Most surprises with image workflows fall into a few families: the step refused to run with the chosen model; the
picture came back in another frame or size; the model changed something it should have kept; or the price was not
the estimate. Find the symptom below; each links to the page that explains the mechanism.
The run’s result tells you where to look: every step reports its status, its error code and message, and its credits
(get_execution over MCP, GET /api/v1/executions/{id}).
These stop the step before any charge: nothing was sent to the model.
| Code |
What happened |
Fix |
MODEL_TAKES_ONE_IMAGE |
The step needs several pictures — a person and a garment, a product and a reference — and the chosen model reads one |
Use a model that reads several, such as the node’s default (How AI image steps work) |
MODEL_IGNORES_INSTRUCTIONS |
Something is connected to instructions and the chosen model reads no text |
Choose a model that reads a prompt, or disconnect the instructions (How AI image steps work) |
MODEL_ONE_IMAGE_PER_CALL |
variants above 1 on a model that makes one picture per call |
Set variants: 1, or choose a model that makes several |
UPSCALE_FACTOR_NOT_SUPPORTED |
The upscaler cannot make the factor asked |
Use 2x or 4x with a model that supports it (AI edits) |
MISSING_INPUT, MISSING_PROMPT |
A required picture or prompt did not arrive |
Connect it; if it comes from an earlier step, check that step’s result |
| Symptom |
Cause |
Fix |
| A square picture when you wanted 16:9 or 4:5 |
No frame was set, and the model’s default is square |
Set the node’s aspect_ratio, or the model’s own setting, which wins (How AI image steps work) |
| An ad in 16:9 instead of 1.91:1, a banner in 21:9 instead of 3:1 |
The model makes the nearest proportion it supports |
Crop to the exact size with Resize for Platform |
| An edit returns a slightly different size (896 instead of 900, or larger) |
The AI edit model decides its output size |
End with Resize when the size matters (AI edits) |
| A photo from a phone lies on its side |
Image steps turn photos upright from their orientation tag; this file was stored sideways without one |
Turn it with Rotate (Files and formats) |
| Symptom |
Cause |
Fix |
| The product’s shape, label or decoration changed |
A general node (Image Transform, Text to Image) was used, or the prompt did not say what must stay |
Use a product node, which is told to keep the product; in a free prompt, say first what must not change (Generating and editing with a prompt) |
| An effect (embroidery, foil) spread over the whole product |
The node could not tell the design from the product |
Connect the blank product on blank_product_image (Designs on products) |
| A person’s clothes under the garment changed, a jacket came buttoned |
The model decides what you did not set |
Say it in custom_prompt, or pick among variants (People and fashion) |
| The pose reference was ignored in a try-on |
The model reads fewer pictures than connected, so the pose picture was left out and the pose preset used |
Use the default model, which reads up to 14 pictures |
| Reframe or Outpainting redrew the subject |
A free prompt asked for more than new surroundings |
Leave the prompt empty, or describe only the new area |
| Symptom |
Cause |
Fix |
| A word in the picture is misspelled |
The model draws letters as shapes |
Generate without text and set it with Text on Image, in your fonts; or use a model good at text (Generating and editing with a prompt) |
| A removed object came back as a sign with words on it |
The prompt of a fill step was an instruction, and the model painted it |
Describe what should be there — “the table continuing, empty” — not what to do (AI edits) |
| A negative prompt had no effect |
The default models do not take one |
Say what you want in positive terms: “on a plain background” |
| Symptom |
Cause |
Fix |
| A logo covers the whole picture |
Overlay does not resize, and an SVG becomes 2048 px on its longest side |
Resize the logo first, with mode: fit (Compositing) |
| A cut-out shows a black or white background |
The file was saved in a format without transparency |
Keep PNG or WebP; JPEG puts white under transparency (Files and formats) |
| A step refuses a PDF or another document |
Image steps read pictures, not documents |
Use a document step, or a picture of the page (Files and formats) |
| Symptom |
Cause |
Fix |
| Variants look almost the same |
Variants of a product node share one prompt |
Change a preset between steps, or use Magic Box, where each variant is a different idea |
| Pictures of a catalogue look like different shoots |
Every AI step invents part of its picture |
Give them one reference picture and the same presets (Consistency and brand) |
| A picture cannot be made again |
Most models do not repeat without a seed; Magic Box never repeats |
Save the pictures you like; use a seed on the models that honour one |
| Symptom |
Cause |
| A vision or text step cost less than estimated |
It is charged by the words actually read and written; the estimate is an upper bound (How AI image steps work) |
| Magic Box cost a little more than its pictures |
Its thinking before drawing is charged at its real cost, well under half a credit per picture (Magic Box) |
| A step with a model setting cost more |
Some settings are priced — a 4K resolution, more pictures — and the estimate includes them (How AI image steps work) |
A run’s estimate and charge are shown before and after it runs; the credits of each step are in its result.
