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.0.0","updated":"2026-04-06T00:00:00.000Z","parent":"higgsfield"}

Higgsfield Troubleshooting Guide

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
• 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 preset — e.g., Animalization needs a subject who can logically transform

---

Problem: Image-to-video barely moves / is static

Cause: Prompt re-describes the static elements instead of what should animate Fix:

• Only describe what changes or moves — not what is already visible in the image
• Add an explicit camera movement: "Camera: Dolly In" or "Camera: slow Arc"
• Specify the motion type: "hair gently lifts", "eyes blink", "she turns slowly left"
• Add atmospheric motion: "dust floats upward", "light flickers", "steam rises"

---

Problem: VFX preset looks too artificial / cartoonish

Cause: Wrong model for the preset, or prompt style conflicts with effect Fix:

• For grounded presets (Explosion, Freezing): use Kling 3.0 or 2.6 for realism
• For stylized presets (Animalization, Multiverse): use Wan 2.5 — leans into the style
• Add "photorealistic", "physically accurate", "cinematic quality" to the prompt

---

Problem: Product shots look cheap or over-lit

Cause: No lighting specification, background too plain Fix:

• Specify the background surface: "raw concrete", "warm wood grain", "black velvet"
• Add specific lighting: "soft side-light", "overhead product lighting", "practical only"
• Add texture cues: "camera reveals material grain", "surface catches light on edges"
• Use Nano Banana Pro for maximum image sharpness on product images

---

Problem: Horror/dark content getting blocked

Cause: Platform safety filters triggering on explicit content Fix:

• Describe outcomes rather than explicit acts: "aftermath", "tension", "dread"
• Use atmosphere language: "unsettling", "wrong", "something is off"
• Use the motion presets for horror effects rather than explicit descriptions
• Avoid direct descriptions of injury, gore, or explicit threat

---

Motion Control Failures (Kling 3.0)

When a Kling 3.0 Motion Control generation comes back wrong, the cause is almost always upstream of the prompt — the motion reference clip, the character image, or the orientation/scene-source settings. Walk this list before you regenerate.

Symptom	Root cause	Fix
Output suddenly jumps or snaps mid-clip	The motion reference contains a hidden cut, dissolve, or hard transition	Re-trim the reference to a single continuous shot. If the source clip can't be cleaned up, reshoot or pick a different reference
Output is shorter than the reference clip	The source motion is too fast or too dense for clean transfer	Slow the source (50–75% playback baked in), reshoot at a calmer pace, or pick a reference with simpler motion
Character face drifts or warps across the clip	The character image doesn't have a clearly readable face — bad framing, low light, or the face is too small in frame	Re-shoot or re-generate the character image with closer framing, even lighting, and a neutral or slight expression
Body motion looks correct but the face is dead or frozen	Wrong orientation mode for the shot — Image Orientation when you needed Video Orientation, or vice versa	Switch modes: Video Orientation for full-body movement (dance, action); Image Orientation for camera-driven shots with a mostly static body. Regenerate
Generated character feels detached from the environment	Scene source is set incorrectly — pulling the wrong background	Decide whether the environment should come from the motion video or the character image, then set Scene source accordingly
Motion transfers but identity drifts across the clip	The character image isn't full enough — head or body is cut off, or framing is too tight to anchor identity	Re-upload a character image that shows both head AND body fully; this is what Element Binding needs to keep the face stable through movement

For the full Motion Control workflow and pre-flight input checklist, see ../higgsfield-motion/SKILL.md → "Kling 3.0 Motion Control — When and How to Run It" and "Motion Reference Input Checklist".

---

Problem: Audio/lip-sync not working or out of sync

Cause: Head motion tokens competing with lip engine, non-MP3 format, clip too long Fix:

• Remove all head/face motion tokens (nodding, turning head, looking around)
• Keep dialogue clips 3–8s (not 15s — accuracy degrades)
• Use MP3 format only for Seedance 2.0 (when available) (WAV/AAC fail silently)
• Lock camera: medium close-up, static or slow Dolly In only
• One face per shot — multiple faces break audio routing
• For detailed audio guidance → higgsfield-audio skill

---

Problem: Background music overrides uploaded dialogue

Cause: Ambient/music tokens in prompt invite generative audio engine to replace your audio Fix:

• Add timestamp anchoring: "Audio @Audio1 plays exactly as uploaded from 0s to end"
• Remove ALL ambient/SFX/music tokens from the prompt
• Keep the prompt focused on visual description + dialogue only

---

Pre-Generation Checklist

Before generating, verify:

• Subject described clearly (who/what)
• Action described specifically (what happens)
• Camera named with exact preset name
• Visual style specified (Cinematic / VHS / etc.)
• Color grade or lighting mentioned
• Aspect ratio included
• Model selected (or let Higgsfield default)
• Prompt is under 200 words
• No conflicting instructions
• Soul ID referenced if character consistency needed
• Motion preset named at end if using one
• Identity Block separated from Motion Block (if Soul ID active)

---

Full negative constraints reference: For a comprehensive, categorized list of all generation artifacts and the prompt phrasing to prevent them, see ../shared/negative-constraints.md. This troubleshooting guide covers diagnosis and fixes; the shared constraints file covers prevention.

---

Cinema Studio 3.0 / Seedance 2.0 Diagnostic Tree

These diagnostics apply to Cinema Studio 3.0's generation engine (Business/Team plan only). For Cinema Studio 2.5 issues, see the general troubleshooting section above.

Quick Diagnostic

Symptom	Likely Cause	Fix
Output blurry, jittery, or morphing	Overspecification — prompt too long or too detailed	Cut prompt to 30–100 words. Use @reference images/videos instead of 50+ words of description
Camera chaotic, spinning, or jittering	Violated the One-Move Rule — multiple camera moves in one shot	Rewrite to ONE primary camera move per shot. Use Cinema Studio 3.0's Smart mode, or split into multi-shot
Character doesn't match reference	Prompt is re-describing the character's appearance	Delete ALL physical descriptions. Describe ONLY action and emotion. The @reference carries identity
Action stiff or lacking impact	Missing intent/physics language	Add degree adverbs (violently, gently, explosively) and physics consequences (dust erupts, sparks fly, fabric tears)
Output "not what I wanted" (vague)	Ambiguous prompt with subjective language	Run Anti-Slop Check: replace beautiful, stunning, epic, amazing, dynamic with observable, measurable details
Audio not matching video	Audio description conflicting with visual description, or uploaded audio being overridden	Use timestamp anchoring for uploaded audio. Remove ambient/SFX tokens when using @Audio references

Diagnostic Flowchart

Output bad?
├── Blurry/morphing → Is prompt > 100 words?
│   ├── Yes → Cut to 30–100 words, use @reference
│   └── No → Too many action beats? (>2 per 5s) → Split into multi-shot
├── Camera wrong → How many camera moves specified?
│   ├── Multiple → Reduce to ONE move (One-Move Rule)
│   └── One → Try Smart mode instead, or use @Video camera transfer
├── Character wrong → Does prompt describe character appearance?
│   ├── Yes → Delete appearance, keep only action/emotion
│   └── No → Use better reference (frontal + 3/4 + profile shots)
├── Action weak → Does prompt have physics language?
│   ├── No → Add degree adverbs + physical consequences
│   └── Yes → Reduce beat density (1–2 beats per 5s)
└── Just bad → Run Anti-Slop Check
    ├── Found slop words → Replace with specific observables
    └── Clean → Try different genre setting, or use @reference

Success Rate Note

Cinema Studio 3.0's generation engine produces ~90% usable output. If outputs are consistently bad across multiple attempts, the prompt is almost certainly the problem — not the model. Apply the diagnostic tree systematically before regenerating.

---

Log the Outcome — Always

Troubleshooting that isn't logged is troubleshooting the next session repeats. After ANY confirmed fix from this skill, write it to the learning memory (../../higgsfield_memory.py, databases in ../../db/):

• Filter workaround confirmed (the rewritten prompt passed in a real generation): python3 seedance_lint.py --confirmed "<prompt that passed>"
• Quality fix confirmed (the improved prompt fixed motion / identity / blocking / audio): python3 higgsfield_memory.py add-quality '<json>' with original_prompt, failure_description, improved_prompt, model_used — then update-quality <id> improved once verified.
• Outcome learned later for an entry that already exists: python3 higgsfield_memory.py update-filter <id> <fixed|workaround|still-blocked>
• Project-specific lessons: add --project <name> to keep them scoped under ../../db/projects/ instead of global memory.

Before troubleshooting, also CHECK memory first — that's higgsfield-recall's job (query-filter / query-quality); the preflight's MEMORY RECALL section does it automatically.

---

Vision-Grounded Diagnosis — Classify the Rejected Still, Don't Guess

The reject_reason you log feeds the iterate-vs-batch fork (higgsfield-recall § Read the verdict). Logged from memory it's hearsay — "I think the face drifted." When you can actually see the rejected output, classify it from the frame instead of from recall. This is an opt-in assist ("diagnose this rejected shot"), and it is advisory: vision proposes, the human confirms.

Scope (v1): stills only — an image, or a single representative frame the user picks from a video. Full-clip motion failures (FPS drift, temporal de-dup, multi-motion) are out of scope here; they need frame-by-frame review (../higgsfield-seedance/FAILURE-MODES.md), not a single-frame classify.

The chain:

1. Capture. Get the still in hand. Local image → read it directly. Web URL → media_import_url (never pass a raw URL). Cowork local file → the upload widget. Outputs are not auto-saved, so capture is an explicit step.
2. Classify against the reject_reason enum (the table below). Note what you see in one line (the vision_evidence).
3. No clean home → other + note. Some visible failures (warped hand, FPS drift) have no exact enum value. Route to other with the evidence note; never force-fit a near-miss. If the other pile grows, that's the data that justifies a future enum-extension PR.
4. Confirm, then log. Surface the proposal — "vision says physics (warped left hand, center frame); confirm or correct?" — then:

   python3 ../../higgsfield_memory.py log-gen <project> --model <id> \
     --tags <shot_tags> --outcome rejected --reason <confirmed> \
     --vision-reason <proposed> --vision-evidence "<one line>"
   

   --reason is the human verdict (drives the fork); --vision-reason is the proposal (feeds the agreement gate). Logging both is what lets the tool learn.

Mapping table — what vision sees → reject_reason:

Vision observes	reject_reason
face / identity changed vs reference	identity-drift
wardrobe or colour shifted vs reference	wardrobe-contamination
extra cuts / unwanted scene breaks	extra-cuts
staging or blocking broken	blocking-broken
flat / wrong performance	performance
wrong camera move	camera-wrong
physics or anatomy violation (incl. warped hand)	physics
garbled on-screen text	text-render
provider content-filter block	filter-flagged
bad framing / composition	composition
FPS drift, temporal de-dup, or no clean home	other + evidence note

Measure before trusting. Vision is the fork's accuracy backstop only once proven. python3 ../../higgsfield_memory.py agreement <project> reports, per reject_reason class, how often the proposal matched the confirmed verdict. A class is trusted (vision may be logged without confirmation) only above the agreement gate over enough confirmed diagnoses; until then, confirm every one.

---

Related skills

• higgsfield-prompt — MCSLA formula, prompt structure, Identity/Motion separation
• higgsfield-recall — Pre-generation memory check for past failures
• higgsfield-models — Model selection (wrong model = many quality issues)
• higgsfield-audio — Audio-specific failures and fixes
• higgsfield-cinema — Cinema Studio–specific issues (512 char limit, @ Element bugs)
• ../shared/negative-constraints.md — Prevention-focused constraint reference