/higgsfield-troubleshoot

name: higgsfield-troubleshoot
description: >
  Use when a Higgsfield generation fails, produces poor quality, looks wrong,
  doesn't match the prompt, or the user needs to fix or improve an output.
user-invocable: true
metadata:
  tags: [higgsfield, troubleshoot, fix, quality, failure, improve]
  version: 3.3.1
  updated: 2026-09-26
  parent: higgsfield

Higgsfield Troubleshooting Guide

QUICK FACTS

*Generated-checked block (scripts/build_index.py verifies anchors). Read the linked sections for full context — these lines are routing aids, not the rules themselves.*

• Face inconsistency, dead camera moves, ignored prompts, static i2v, blocked dark content — the per-problem fix list [→](#common-problems--fixes)
• Kling 3.0 Motion Control failures are almost always upstream of the prompt: reference clip, character image, or orientation/scene-source settings [→](#motion-control-failures-kling-30)
• Pre-generation checklist: subject, action, named camera preset, style, grade, aspect, <200 words (short-form regime) [→](#pre-generation-checklist)
• Seedance/Cinema Studio symptom table + diagnostic flowchart: blurry = overspecified; chaotic camera = One-Move Rule violated; wrong character = prompt text contradicts the reference — delete the contradicting text first; delete ALL appearance text only on a start-frame / I2V shot (P1-1) [→](#cinema-studio-30--seedance-20-diagnostic-tree)
• Every delivered take gets ONE of five verdicts before anything re-fires: keep / fix-in-post / edit / re-roll / rewrite [→](#take-triage--five-verdicts-for-a-delivered-take)
• Two takes with the same flaw = rewrite, by rule; different flaws per roll = stochastic → batch-and-cull, not rewrite — against Retry Ladder rung 2 when both takes failed: OPEN, no default (§ Stop-Rule Ladder) [→](#take-triage--five-verdicts-for-a-delivered-take)
• Re-roll = same prompt again, unchanged — no seed parameter on this surface; every roll is a fresh sample [→](#take-triage--five-verdicts-for-a-delivered-take)
• Change exactly one variable between takes so causality stays readable [→](#one-variable-per-retake)
• Declare the take budget AND a written "good enough" bar before take one; half-budget with no progress forces a strategy change [→](#attempt-budget--declared-before-take-one-heuristic)
• The shot log is the ledger row — one line per take, changed variable in `notes` [→](#the-shot-log-is-the-ledger-row)
• Continuation/extension defects: 12-row symptom → cause → single-repair-variable atlas (planned-vs-observed opening, motion-vector drop, prop contradictions, chain-depth drift…) [→](#sequence--continuation-failure-atlas)
• Retry Ladder: 4 terminating rungs — re-run once verbatim → treat 2nd failure as over-packing (when the two failures differ, Take Triage reads them as stochastic: OPEN, no default — § Stop-Rule Ladder) → switch model for that shot → stop after 3 paid attempts with named options [→](#retry-ladder--a-failed-take-edits-the-plan-not-just-the-dice)
• Six stop numbers, one ladder: 2 same-flaw re-rolls → rewrite · 3 paid attempts (no declared budget) → named options · half a declared budget with no progress → change strategy · 4 v2v batches (ceiling) → prompt/source fault · 10–15 surgical iterations (declared budget) → simplify the shot · 65–100 generations per kept shot is a project benchmark, never a stop rule. The earliest tripwire wins; where 2 and 4 count the same v2v runs it is OPEN, default the earlier stop [→](#stop-rule-ladder--which-number-governs)
• Log EVERY confirmed fix to learning memory, and check memory first before troubleshooting [→](#log-the-outcome--always)
• Vision-grounded diagnosis (stills only): vision proposes the `reject_reason`, the human confirms — advisory until a class clears the agreement gate [→](#vision-grounded-diagnosis--classify-the-rejected-still-dont-guess)

Common Problems & Fixes

Problem: Character face is inconsistent or morphing

**Cause:** No Soul ID reference; prompt has conflicting appearance descriptions **Fix:**

• Create a Soul ID reference and use it in subsequent generations
• Remove any appearance descriptions that contradict each other
• For image-to-video: don't re-describe the face — let the input image carry it
• Use Kling 3.0 for best character consistency (or Kling 2.6 if no audio needed)

---

Problem: Camera movement isn't working / is generic

**Cause:** Camera described vaguely, not using exact preset names **Fix:**

• Replace generic descriptions with exact preset names: "Dolly In", "FPV Drone", "360 Orbit"
• Put the camera instruction on its own line or clearly labeled: "Camera: [name]"
• Don't describe what the camera is doing in prose — name the control directly

---

Problem: Prompt is ignored / output doesn't match

**Cause:** Prompt too long, conflicting instructions, over-specified **Fix:**

• Cut prompt to under 200 words — trim the least essential details (short-form prompts only; block-scaffold production briefs are a different regime — root `SKILL.md` HARD RULE 8)
• Remove any contradictory elements (don't say both "moving fast" and "frozen in place")
• Lead with the most important element: Subject → Action → Camera → Style
• Split complex scenes into multiple separate generations

---

Problem: Visual style looks wrong / generic

**Cause:** No style specified, or style description too vague **Fix:**

• Add one of the named styles: Cinematic / VHS / Super 8MM / Anamorphic / Abstract
• Add a specific color grade description: "cold teal and orange", "warm golden amber"
• Specify aspect ratio: 16:9 / 9:16 / 2.35:1
• Add lighting: "golden hour", "neon", "practical only", "overcast"

---

Problem: Motion preset effect isn't visible

**Cause:** Preset not explicitly named, or scene context doesn't support the effect **Fix:**

• Name the preset exactly as it appears in the library: "Apply Explosion preset"
• Place the preset instruction at the end of the prompt, clearly labeled
• Make sure the scene context supports the pres