Generation Failures¶

When the Generation Runner finishes and some nodes didn't produce acceptable output. This page covers diagnosis and recovery.

Diagnostic flow¶

flowchart TD
    A[Generation done<br/>but something's wrong]
    A --> B{Did errors.json<br/>get created?}
    B -->|YES| C[Open errors.json<br/>see Common Errors]
    B -->|NO| D{Did images generate<br/>but look wrong?}
    D -->|YES| E[Visual diagnosis]
    D -->|NO| F{Did some nodes<br/>silently skip?}
    F -->|YES| G[Sanity check failed silently]
    F -->|NO| H[Check Generation Runner logs]

Errors that surface in `errors.json`¶

These are the runner reporting that a node failed all its retries.

See Common Errors for the full table. Quick reference:

Error	What it means	First thing to try
`content_policy`	Safety filter tripped	Rerun (different seed often works)
`timeout`	Took too long	Bump `timeout`, rerun the single node
`connection refused`	G-Labs dropped	Restart G-Labs, rerun
`model not available`	API rejected the model	Verify `model: "nano_banana_2"` on the node
`api_error`	Generic G-Labs API failure	Check the G-Labs console for actual error text

Generated images look wrong (no errors.json)¶

Generations completed without errors but the output doesn't look right. Different causes need different fixes:

Image looks unrelated to the prompt — generic supermarket / kitchen / cafe¶

Cause: Dynamic variableName doesn't match the template placeholder. The literal string {scene} was sent to NanoBanana.
Diagnosis: Open the .nbflow. Find a Dynamic Prompt feeding a template. Compare its variableName to the placeholder in the template's text.
Fix: Set variableName to the placeholder identifier (e.g. scene, dialogue, pose). Re-run the sanity check, regenerate.

Image is NB1 quality, not NB2¶

Cause: model field missing or set to wrong identifier. G-Labs defaulted to NanoBanana 1.
Diagnosis: Check properties.model on the NanobananaAPI node. Should be "nano_banana_2".
Fix: Set the model property. Run the sanity check before regenerating.

Image doesn't include the avatar's face / wardrobe¶

Cause

The reference image link is broken — either the per-node refs are stale (renumber bug) or the Cached Media swap dropped the input slot.

Diagnosis

Open the .nbflow in PatchWork's UI. Does the canvas show the avatar reference Media node connected to the gen node?
If the UI shows connected: the runner may have used a wrong reference. Check the avatar reference R2 URL is current.
If the UI shows disconnected: per-node link refs are stale. The headless runner may have used the central array (which had the link) but the UI shows orphan.

Fix

Run resync_link_refs(tab) from manager/scripts/_lib_link_refs.py on every tab. Re-save. Verify in PatchWork UI that the connection now renders.

Image has hands with extra fingers / melted face / garbled limbs¶

Cause

Normal AI-tells. The visual QA pass should have caught and auto-rerun these.

Diagnosis

Check Assets/{workflow}/qa_loop/v0-N/ — did the runner already attempt regens (sceneNN-r2.png, sceneNN-r3.png)? If yes, it tried 3 times and gave up.

Fix

Bump the regen attempt cap: re-invoke the runner with "up to 10 attempts" specified.
If still failing after 10: tighten the prompt around the problem area. Common fixes:
Add --no extra fingers, extra hands, distorted limbs, malformed anatomy to the negative prompt
Reduce the number of hands visible in the scene (frame the shot so only one hand is in frame)
Pose the hands flat against a surface (less ambiguity than freely posed)

Image has hallucinated text (price tags, signage, product labels)¶

Cause: Normal. NanoBanana routinely produces garbled text.
Fix: Don't bother. Text in generated images is low priority — fix identity, composition, wardrobe, pose, setting first. Garbled background text reads as "real candid phone footage" and rarely matters.

Image has the wrong number of subjects (e.g. 2 avatars where there should be 1)¶

Cause

Prompt is ambiguous or the reference image showed multiple people.

Diagnosis

Check the prompt — does it explicitly state "one person" / "single subject"? Check the reference image — is it a single-person shot?

Fix

Add explicit subject count to prompt: "Single subject, one person only, alone in frame"
Add --no group of people, multiple subjects, two people, second person, duplicate person to negative prompt
If the ref image is multi-person, swap to a single-person ref

Video clips look wrong¶

Avatar's face drifts mid-clip¶

Cause

Veo's interpolation drifts when start and end frames are too different, or when the prompt asks for motion that requires more than 8 seconds.

Fix

For low-movement scenes (talking head): use the same image as start AND end frame
For larger motion: split into a shorter clip (use a tighter motion description, no big body movements)

Avatar moves to a different location mid-clip and it looks glitchy¶

Cause: Location change without an explicit end frame. Veo hallucinates the transition.
Fix: That should be two scenes, not one. Split into separate Veo3 nodes with their own image gens. See Video Prompt Rules.

Distant background animals or birds are glitching across frames¶

Cause: Animals in distant background. Veo's frame-to-frame interpolation breaks on chaotic distant motion.
Fix: Regenerate the start frame image with the animals stripped from the background. Replace with static elements (trees, fences, buildings) or predictable elements (one or two humans walking). Re-run the Veo clip. See Image Prompt Rules.

POV clip looks like third-person — avatar's body is visible¶

Cause: The prompt described the subject's body orientation. Veo flipped to third-person to resolve the contradiction.
Fix: Rewrite the prompt to describe only the camera vantage, what extended body parts reach into frame, and what background is visible. Add --no third person view, external camera, camera facing subject, selfie of subject. See Image Prompt Rules.

Some nodes silently didn't generate¶

Some scenes are missing from the output gallery but no errors.json entry exists.

The sanity check was skipped or failed silently¶

Cause: The runner may have skipped nodes that had broken links or missing properties — depending on the runner version, this can happen without a hard error.
Diagnosis: Run the pre-generation sanity check on the input .nbflow. If it surfaces issues, those nodes were probably silently skipped.
Fix: Fix the schema issues per the sanity check output. Regenerate.

A required reference image upload failed¶

Cause: The runner couldn't upload a local reference image to R2 — maybe the file path was wrong, or the R2 upload Worker was unavailable.
Diagnosis: Check the runner's console output for R2 upload errors during the run.
Fix: Verify the reference image path is correct. Verify the R2 Worker is up. Regenerate.

After fixing¶

Don't regenerate the entire workflow if only a few nodes need rerunning. Use the per-node rerun helper:

python manager/scripts/regen-nodes.py \
  path/to/workflow.nbflow \
  --node-ids 14 23 45 \
  --server "<tunnel-url>" \
  --api-key "..."

This is faster than re-running the full workflow and preserves the candidates the user has already picked for other nodes.

Generation Failures¶

Diagnostic flow¶

Errors that surface in errors.json¶

Generated images look wrong (no errors.json)¶

Image looks unrelated to the prompt — generic supermarket / kitchen / cafe¶

Image is NB1 quality, not NB2¶

Image doesn't include the avatar's face / wardrobe¶

Image has hands with extra fingers / melted face / garbled limbs¶

Image has hallucinated text (price tags, signage, product labels)¶

Image has the wrong number of subjects (e.g. 2 avatars where there should be 1)¶

Video clips look wrong¶

Avatar's face drifts mid-clip¶

Avatar moves to a different location mid-clip and it looks glitchy¶

Distant background animals or birds are glitching across frames¶

POV clip looks like third-person — avatar's body is visible¶

Some nodes silently didn't generate¶

The sanity check was skipped or failed silently¶

A required reference image upload failed¶

After fixing¶

Errors that surface in `errors.json`¶