# Higgsfield Troubleshoot > > - **Type:** Skill - **Install:** `agentstack add skill-osidemedia-higgsfield-ai-prompt-skill-higgsfield-troubleshoot` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [OSideMedia](https://agentstack.voostack.com/s/osidemedia) - **Installs:** 0 - **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [OSideMedia](https://github.com/OSideMedia) - **Source:** https://github.com/OSideMedia/higgsfield-ai-prompt-skill/tree/main/skills/higgsfield-troubleshoot - **Website:** https://higgsfield.ai ## Install ```sh agentstack add skill-osidemedia-higgsfield-ai-prompt-skill-higgsfield-troubleshoot ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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 ""` - **Quality fix confirmed** (the improved prompt fixed motion / identity / blocking / audio): `python3 higgsfield_memory.py add-quality ''` with `original_prompt`, `failure_description`, `improved_prompt`, `model_used` — then `update-quality improved` once verified. - **Outcome learned later** for an entry that already exists: `python3 higgsfield_memory.py update-filter ` - **Project-specific lessons**: add `--project ` 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: ```bash python3 ../../higgsfield_memory.py log-gen --model \ --tags --outcome rejected --reason \ --vision-reason --vision-evidence "" ``` `--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 ` 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 ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [OSideMedia](https://github.com/OSideMedia) - **Source:** [OSideMedia/higgsfield-ai-prompt-skill](https://github.com/OSideMedia/higgsfield-ai-prompt-skill) - **License:** MIT - **Homepage:** https://higgsfield.ai Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-osidemedia-higgsfield-ai-prompt-skill-higgsfield-troubleshoot - Seller: https://agentstack.voostack.com/s/osidemedia - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.