version: "1.0.2" 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-06 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.

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

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 (../../scripts/higgsfield_memory.py, databases in ../../db/):

• Filter workaround confirmed (the rewritten prompt passed in a real

generation): python3 scripts/seedance_lint.py --confirmed "<prompt that passed>"

• Quality fix confirmed (the improved prompt fixed motion / identity /

blocking / audio): python3 scripts/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 scripts/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.

1. Classify against the `reject_reason` enum (the table below). Note what you

see in one line (the vision_evidence).

1. 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.

1. Confirm, then log. Surface the proposal — *"vision says physics (warped

left hand, center frame); confirm or correct?"* — then: ``bash python3 ../../scripts/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`:

Measure before trusting. Vision is the fork's accuracy backstop only once proven. python3 ../../scripts/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