> For the complete documentation index, see [llms.txt](https://animotive.gitbook.io/animotive-kimodo/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://animotive.gitbook.io/animotive-kimodo/going-further/troubleshooting.md). # Troubleshooting This page lists the failure modes and warnings the plugin classifies, with the most common cause and the first fix for each. If a generation fails or a row in the **Kimodo Monitor** carries a `⚠` indicator, find the matching category below. ## Symptom index The result imports successfully but does not look right? Start here. **Character lands the motion in an offset pose.** Arms held wider, fingers curled, pelvis floating — consistent across the whole clip. Cause: retargeter rest pose mismatch. Fix: [Verify the rest pose](/animotive-kimodo/setup/first-character.md#6-verify-the-rest-pose) on the Forward retargeter. **Feet slide along the ground.** Cause: no foot constraints keyed; Kimodo had freedom to slide. Fix: add **Left Foot** / **Right Foot** keys on the **Kimodo Constraints** track at the planting frames. The character's foot must be at the intended plant location at each keyed frame (typically via a Control Rig keyframe at the same frame). For ongoing foot-slide during retargeting (the imported clip looks correctly planted on Kimodo's SOMA skeleton but slides on your character), the IK Retargeter has a **Speed-Based Foot Planting** option that locks contact frames using a per-foot speed curve. See Epic's [IK Rig Animation Retargeting](https://dev.epicgames.com/documentation/en-us/unreal-engine/ik-rig-animation-retargeting-in-unreal-engine) documentation; enable speed planting on the Forward retargeter for the character and tune the speed threshold per foot. **Result plays but only the root translates correctly.** Cause: warning `"only Root2D channel keys will contribute"` was raised — the binding has no Control Rig and no animation track, so non-root constraint channels were ignored. Fix: assign a Control Rig to the character (or run the Retarget Wizard with auto-CR), then re-export. **Imported animation does not fight back when scrubbed.** The Control Rig section still shows handles but no character motion. Cause: the auto-mute did not catch the right range, or you un-muted CR manually. Fix: mute the overlapping Control Rig section over the injected range, or delete the duplicate keys. **Pose change in Sequencer is ignored by the generation.** Cause: the keys were set on the wrong rig (often the face Control Rig). Fix: confirm Control Rig keys are on the **body** sub-binding (`Body` for MetaHumans), not on the face binding. **Warning chip on the Animotive Kimodo track row.** Hover the chip to read which retargeter slot is unresolved. Fix: right-click the track → **Re-Detect Retargeters**. If that does not resolve, run the Retarget Wizard for the character and re-detect. ## Common scenarios **Run reaches Completed with `⚠`** — the generation succeeded and the animation is on the timeline, but a non-terminal warning was raised. Hover the `⚠` chip and read the tooltip; the result is usable, but understand the underlying condition before scaling the workflow up. **Run fails at Processing** — usually `ServerSolveFailed` (the model could not solve the requested motion) or `RemoteServerError` (the server itself returned an error). Simplify the prompt, verify the two key poses are physically reachable from one another, and try again. If the failure persists with a known-good prompt and pose pair, check server health. **Run fails before Uploading** — a pre-request failure. The friendly message names the specific category (`PreRequestNoSequence`, `PreRequestNoBinding`, `PreRequestSetupFailed`, `PreRequestBuildFailed`). Confirm a sequence is open, the binding is correct, the `Saved/Kimodo` folder is writable, and the section's data is well-formed. **Run stuck at Queued** — the backend has not responded. Confirm the **Active Backend** setting under **Edit → Project Settings → Plugins → Kimodo Exporter**: Docker Desktop running and the `kimodo_gen` service up for **Local (Docker)**, or the configured **Server URL** responding for **Self-Hosted (HTTP)**. ## Export error modal Whenever an export can't reach the result you asked for, a pop-up appears so you don't have to be watching the log or the Monitor to notice. It fires the moment the blocker is detected — for **any** backend (Local Docker, Self-Hosted, or Animotive) — and shows a friendly one-line summary, the underlying detail verbatim in a scrollable, selectable box, and a **Copy** button. * **Title.** Most blockers read **"Kimodo Export — Couldn't Complete This Request"**. Account problems on the Animotive backend (insufficient tokens / rejected API key) read **"Animotive Kimodo — Account Problem"** and, for an exhausted balance, add a **kimodo.animotive.com** link. * **Detail heading.** Server-origin errors show the text under **"Server response:"**; local errors (missing retargeter, file write, etc.) show it under **"Details:"**. * **When it appears.** Every terminal failure (see *Terminal failure categories* below) raises it, plus the two **result-denying** warnings — `PostExportInjectionFailed` (the animation solved but never landed in Sequencer) and `CRAutoGenSkipped` (no posing surface was created). The cosmetic fallback warnings `ResolverFallback` and `RetargetFirstFallback` do **not** pop the modal, because the result is still delivered — they stay as a `⚠` on the Monitor row. * **One per request.** At most one modal appears per generation, even if several blockers fire. * **Additive.** The modal never replaces the **Kimodo Monitor** row — the failure (or warning) is still recorded there with its category. Use **Copy** to grab the exact text for a bug report. ## Terminal failure categories | Category | Friendly message | Common cause | First fix | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `NetworkUnreachable` | "Couldn't reach the Kimodo server. Check your connection or contact pipeline." | Configured **Server URL** is wrong, server is down, or firewall/VPN is blocking. | Confirm the URL in plugin settings; try opening it in a browser from the same machine. | | `ServerSolveFailed` | "Kimodo couldn't solve this animation. Try simplifying the prompt or adjusting key poses." | The model could not produce a valid in-between for the prompt + pose combination. | Shorten or rephrase the prompt; verify the two key poses are physically reachable in the section's duration. | | `MissingIKRetargeter` | "No IK retargeter found for this skeleton. Run setup before exporting." | The character's skeleton has no matching IK Retargeter assets. | Run the **Animotive Kimodo Retarget Wizard** on the character; then **Re-Detect Retargeters** on the track. | | `InvalidSkeleton` | "The bound skeleton isn't compatible with Kimodo. Use a SOMA77 or MetaHuman rig." | The binding is a face/prop/accessory rig, not a body rig. | Target the body sub-binding (typically `Body`); ensure the skeleton has a `pelvis` or `root` bone. | | `FileWriteFailed` | "Couldn't save the result. Check your project's Saved folder permissions." | The project's `Saved` folder is read-only, full, or owned by another user. | Confirm the editor can write to `/Saved/`; check drive free space. | | `RetargetFailed` | "Retargeting failed during import. Verify the IK retargeter mapping for this skeleton." | The Forward retargeter is missing chains, has bad mappings, or targets the wrong skeleton. | Open the Forward retargeter named on the track; check chain mapping against the bound skeleton; re-run the wizard if needed. | | `RemoteServerError` | "Kimodo server returned an error or no data. Try again or contact pipeline." | The server returned an error response, an empty payload, or a malformed envelope. | Retry once; if persistent, check server health and inspect the editor's Output Log. | | `PreRequestNoSequence` | "No Level Sequence is open in Sequencer. Open a sequence and try again." | **Generate with Kimodo** clicked while Sequencer was empty/closed. | Open the Level Sequence containing the character, then retry. | | `PreRequestNoBinding` | "No skeletal mesh binding found in this sequence. Add a body skel-mesh binding (or an Animotive Kimodo track) and try again." | The sequence has no body binding, or only face/accessory bindings. | Add the character's body sub-binding to the sequence; add an Animotive Kimodo track to it. | | `PreRequestSetupFailed` | "Couldn't prepare export workspace. Check your project's Saved/Kimodo folder permissions." | The plugin could not create or write into `/Saved/Kimodo`. | Confirm the folder is writable and not locked by another process. | | `PreRequestBuildFailed` | "Couldn't build the Kimodo request body. See log for details." | A sequence-side data problem prevented payload assembly (malformed prompt, invalid binding mid-build, etc.). | Open the editor's Output Log; find the matching `LogKimodoExporter` entry; resolve the underlying issue. | | `UnconfiguredBackend` | "Animotive Kimodo backend isn't configured. Open setup via Tools → Animotive Kimodo → First-Run Setup." | **Generate with Kimodo** was clicked while the active backend's required fields were empty, and the first-run setup popup was cancelled instead of completed. | Open **Tools → Animotive Kimodo → First-Run Setup**, fill the required fields for the chosen backend (Remote: `Server URL`; Docker: `Compose Dir` + `Host Export Dir`), click **Save & Setup**, then re-export. See [First-Run Setup Popup](/animotive-kimodo/setup/first-run-setup.md) for the full field reference. | | `InsufficientTokens` | "Your Animotive token balance is insufficient. Find out more at kimodo.animotive.com." | Animotive (hosted) backend returned HTTP 402 / 403 — account is out of generation tokens. | Top up at [kimodo.animotive.com](https://kimodo.animotive.com/) (the error modal carries a direct link). | | `InvalidApiKey` | "Your Animotive API key was rejected. Check the key in plugin settings, or use 'Test API Key' to verify it." | Animotive backend returned HTTP 401 — the API key is missing, wrong, or expired. | Re-copy the key from your account portal into **Project Settings → Kimodo Exporter → Animotive API Key**; click **Test API Key** to confirm. | | `Unknown` | "An unexpected error occurred during the Kimodo pipeline. See the log for details." | An error path not yet classified into a specific category. | Capture the surrounding `LogKimodoExporter` lines for a bug report. | ## Non-terminal warning categories | Category | Friendly message | Common cause | First fix | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ResolverFallback` | "Sibling Control Rig not found for the Animotive Kimodo binding. Falling back to the legacy global scan." | The binding owning the Animotive Kimodo track has no sibling Control Rig; plugin used legacy project-wide scan. | Confirm the Control Rig section is on the same binding as the Animotive Kimodo track. | | `RetargetFirstFallback` | "Retarget-first capture failed. Falling back to the Q\_bias path." | Retarget-first is the default export pipeline; it failed at capture for this export, so the plugin reverted to the Q\_bias live-capture fallback. | Check the **Reverse Retargeter** on the Animotive Kimodo track resolved (see the track's warning chip). The Q\_bias fallback still exports, but retarget-first carries the body pose **and root heading** with higher fidelity — fix the retargeter and re-export to use it. | | `PostExportInjectionFailed` | "Animation generated, but Sequencer injection failed. Re-import the BVH manually if needed." | BVH was produced and retargeted correctly, but injection into Sequencer did not succeed. | Locate the retargeted asset under `/Game/Kimodo/Generated//Sequences/` and drag it onto the binding manually. | | `CRAutoGenSkipped` | "Couldn't auto-generate a Control Rig for this skeleton. Wizard continued without one — pose this character with a hand-authored Control Rig, or re-run the wizard after fixing the underlying issue." | Retarget Wizard's auto Control Rig step failed for the target skeleton; IK Rig + retargeters still good. | Assign or author a Control Rig manually, or fix the underlying skeleton issue and re-run the wizard. | ## Retarget failure recovery If a row fails with `RetargetFailed`, or the imported animation lands with obvious twists / wrong limb placement, the cause is on the retargeting side rather than the model side. 1. Open the **Forward Retargeter** named on the Animotive Kimodo track (Soma → Character). 2. Confirm the chain mapping covers every limb on both the source and target skeletons. 3. Check the retarget pose on the target side — see [First-Time Character Setup → Verify the rest pose](/animotive-kimodo/setup/first-character.md#6-verify-the-rest-pose) for the full bind-pose verification procedure. 4. Re-run the Retarget Wizard if the retargeter assets look incomplete or corrupted. 5. Re-run the generation. ## Character rotated 90° after import (X-forward rigs) **Symptom.** Generation succeeds, the BVH lands, retarget finishes — but the imported character ends up facing **90° off** from the source actor. Visible most clearly with a character standing at world yaw 0°: source faces UE +Y world, but after import the imported clip faces UE +X (or vice versa). **Cause.** The Kimodo importer applies a fixed +90° world-Z yaw to the soma anim's root pelvis to swing soma's Z-forward output into UE's Y-forward world. This is correct for Mannequin-style rigs whose pelvis rest faces UE +Y world. For rigs whose pelvis rest faces UE +X world (some Unity-imported rigs, some CC4 outputs, custom rigs authored Z-forward in DCC tools), the +90° push lands the pelvis at +Y instead of +X — exactly the 90° drift you see. **Fix.** Auto-detect runs at import time. If the target rig's pelvis rest pose unambiguously faces UE +X (within \~31° of the +X axis), the importer skips the +90° yaw and the character lands at the correct world facing without any user action. **When auto-detect fails — manual override.** If the auto-detect picks the wrong bucket (ambiguous pelvis around 45°, or a non-standard authoring), pin the basis manually: 1. Open **Edit → Project Settings → Plugins → Kimodo Importer → Coordinate Basis**. 2. Add a row to **Per-Skeleton Basis Override**: * **Key**: the target rig's `USkeleton` asset. * **Value**: * `Auto-detect` — default, lets the importer guess from the rest pose. * `Mannequin (Y-forward)` — force the legacy +90° yaw. * `X-forward` — skip the +90° yaw. 3. Save settings. Re-run generation. The resolved basis is logged on every import — search `Saved/Logs/Kimodo.log` for `target skeleton '' basis = ...` to confirm which path the importer chose. ## See also * [Animotive Kimodo Monitor Panel](/animotive-kimodo/working-in-sequencer/monitor-panel.md) — where these categories surface in the UI. * [First-Time Character Setup](/animotive-kimodo/setup/first-character.md) — retargeter setup and rest pose verification. * [Self-Hosted (HTTP) Backend](/animotive-kimodo/setup/remote-backend.md) — network-side issues underlying `NetworkUnreachable` and `RemoteServerError`.