Docs / Reference / Troubleshooting
Troubleshooting
The symptoms we have seen, and what to check for each.
| Symptom | What to check |
|---|---|
| A setting I changed is not in the window | The column is in the Compact layout, which folds the knobs away without resetting them. The line under Generate Motion names any hidden setting that differs from its default; switch to Full in the header row to see it. See Compact and Full. |
| The Motion Import card is missing, and the Settings switch does nothing | It is a window here, not a card: Animatica ▸ Open Motion Import…. |
| The Animatica menu is not there after restarting Max | Run python scripts/install.py --list and check that the startup folder it prints matches the Max version and locale you are running — Max reads only its own language's profile tree. If no profile was detected at all, start Max once so it creates one, then install again. Then check the Max listener for the plugin's startup line: it names the folder this session loaded from and when that source was last edited. |
| "Local server unavailable" | The plugin could not reach your local MMCP server. The dialog offers three actions: Switch to Cloud, How to start the server (guidance only — Animatica never launches a server process for you), and Dismiss. See the note below before you conclude the server is down. |
| The generation was refused because of my rig | The server decides whether a retarget is needed. If it carries no retarget model and your rig does not match the model's canonical skeleton, the plugin refuses rather than generating something wrong. See the exact wording below. |
| Create Skeleton says joints are missing | An animatica:* rig already exists in the scene, and it does not carry every joint the build needs. Delete the existing rig and create it again — there is no Namespace field here to build a second one beside it. A rig with extra joints is fine and is reused. |
| Create Skeleton built 77 joints, but the model has 30 — and the Console says the server will retarget | By design. When the model's joints all live inside the built-in soma77 rig, that rig is built so you keep the fingers, eyes and jaw the model never predicts, and the server retargets onto it. See What Create Skeleton builds. |
| Create Skeleton built a rig while I was offline, or for a model I did not pick | Both are fallbacks, each logged with its reason: with no server or no sign-in the built-in rig is built; a model the server does not serve is replaced by the first one it does, and the Console names both. Connect, pick the model again, then delete the rig and rebuild if you need that model's own rig. |
| My imported rig is refused: "this hierarchy has only 1 joint … cannot be a character" | You picked a container or helper standing above the rig — an Armature dummy or a group null — rather than the rig itself. Pick the rig's own root joint in the Skeleton picker (the plugin lists it; the helper is not listed). |
| Switching rigs still shows the other rig's prompts and pins | It should not: each rig owns its ruler. If the scene holds prompts and pins that carry no rig identity, pick the rig once — in a one-rig scene the plugin adopts the unowned prompts and pins onto it and says so in the Console. With several rigs it does not guess; delete or re-author. |
| Constraint buttons do nothing | Capture needs a rig. With no skeleton created or picked, the Console shows a warning — create or pick one first. |
| The exported FBX reads wrong in another application | Export through File ▸ Export. The export hygiene rides on Max's export callbacks, so a rig exported any other way does not get it. If the Console or listener printed a line about transforms having moved or offsets not being restored after an export, that is the check reporting a real problem — note the joint names it printed. |
| A button in the window does nothing at all | Open the Console: most failures are logged there as a line rather than raised at you. The startup path also reports its own failures by name ("Failed to open the Animatica tool", "Failed to register the Animatica menu") followed by the traceback in the listener. |
#A busy local server looks like a dead one
The liveness probe waits five seconds. A single-worker local server that is in the middle of answering a generation cannot answer the probe within that window, so it is reported as unreachable even though it is running and working normally. Wait for the run to finish, then press Test in Settings.
#The refusal over a non-canonical rig is deliberate
It is not a failure to work around. When the server carries no retarget model and your rig is not the model's canonical skeleton, the plugin says so in these words:
this server does not support retargeting — use a rig that matches the model's canonical skeleton (Skeleton → Create), or a server with a retarget model
Two ways forward: press Create Skeleton and generate onto the canonical rig, or point the plugin at a server that has a retarget model.