Troubleshooting¶
Most OTS problems are one of three things: nothing was selected, the names don't match, or the range was wrong. This page goes through the symptoms in the order you're likely to meet them.
The window won't open¶
Nothing happens when you run the script.
Almost always Python. Harmony launches user scripts through a system Python 3.9 on PATH, and a 3.10 or newer interpreter is silently ignored — no error, no window.
Install 64-bit Python 3.9, tick Add Python to PATH, and restart Harmony.
An error dialog mentioning a path. The harmony/ folder isn't where the launcher expects it. It should be a folder named octoTransformSync inside your <version>-scripts directory. See Installation.
The shelf button does nothing, or reports an import error. Maya can't find OTS on its Python path. Re-run the drag-and-drop installer — it rewrites the userSetup.py entry and refreshes the shelf button in place.
No OTS tab in the sidebar. The add-on isn't enabled. Check Edit → Preferences → Add-ons, search for Octo Transform Sync, and tick it. Then press N in the 3D view.
The export list is empty¶
You pressed + and nothing appeared. Nothing eligible was selected in the scene. Select the pegs / joints / armature first, then press +.
In Blender, the Scene selection box at the top of the panel tells you exactly what OTS can see — if it says "Select an armature in the viewport", that's your answer.
Some of the selection appeared, but not all. OTS only scans items it can meaningfully export. Effects, composites, and other non-transform nodes aren't transforms and don't come along.
Everything is amber on import¶
This is normal on an empty scene. Amber means "no target found in this scene" — and there's nothing to find yet. Press Create Rig, not Apply.
See The Match Tree.
Some rows are amber¶
The camera row is amber. Expected. On a fresh import there's no joint or bone carrying the camera's name — that's why cameras are counted separately in the summary line. Create Cameras handles it.
A few named rows are amber. The names differ between the two scenes. Fix it by:
- Double-clicking the Target path cell and typing the correct path, or
- Renaming in your scene and pressing Browse… again, or
- Unticking the row if you don't want it.
Most rows are amber. You're probably applying a file to the wrong scene, or you want Create Rig instead of Apply.
Rows stayed amber after Create Rig¶
Expected. The list shows the match state from when you browsed; building the rig doesn't repaint it. Press Browse… again on the same file to re-run the match.
The rig itself is fine — check your scene, not the list.
The animation is wrong¶
Nothing moved after Apply. Apply only writes to rows that are both matched and ticked. Look for amber rows and unticked boxes.
The shot is cut short. The export range didn't cover the whole action. Re-export with Scene range.
It moves, but the rotation is wrong. First check you're not looking at a Z-up Maya scene, where per-key handles are simplified. If the values themselves are wrong rather than the curve shape, that's a bug worth reporting — include the file, both applications' versions, and what the rotation should have been.
A bone is in the right place but its children aren't. You exported a partial chain and the parent it was made relative to isn't in the file. Export the chain from a common ancestor down.
Curves came in as steps. The source keys were stepped, or the rotation travelled as a quaternion — in which case the interpolation type still travels but per-key handles don't, by design. See File Format.
Something about the file¶
"Unsupported version N". The file was written by a different OTS build. There's no backward migration by design; re-export from the source application.
"Missing 'pegs' key" or a format error. You loaded a .pvt in the .anm tab, or the reverse. The file pickers filter by extension, so this usually means the file was renamed.
The file is huge. A wide frame range over a big rig. Tighten the range — only keyed frames plus the range boundaries are sampled, but a hundred pegs over a thousand frames is still a lot of keys.
Cameras¶
The camera doesn't move. In a .anm the motion lives on the camera's peg. Make sure that row was ticked and that you also ran Create Rig or Apply — Create Cameras alone builds the lens, not the move.
The framing is too tight. Check the sensor / film fit in the target application: it should be vertical. Automatic or horizontal fit reinterprets the FOV against the wrong axis and makes everything look zoomed in.
The camera points the wrong way. Cross-application aim is best-effort. Check the roll first, then the tilt. Blender cameras carry a +90° X correction by convention — if a camera has been round-tripped through a hand-edited file, that correction can end up applied twice.
See Cameras.
Rigs¶
Two characters arrived as one. They shared a rig tag on export. Give each root chain its own name in the Rig column and re-export.
I can't split this chain. Correct — a connected chain can never be split across rigs, because a bone in a different armature from its parent has no parent. Merging disconnected roots is allowed; splitting a connected chain isn't. See Rigs & Multi-Rig.
Camera_1 and Camera_2 swapped. They shouldn't — camera chains are sorted by name before numbering, precisely so the numbers are stable between sessions. If they genuinely swapped, the chains were renamed.
Harmony specifics¶
A peg lost its 3D path after Apply. Deliberate, and documented: applying an animation unlinks 3D-path and quaternion-path columns and writes separate-channel bezier curves. The values are right; the authoring mode is gone. Apply onto a Create Rig result instead if you need to keep the original peg intact.
A file that errors cleanly in Maya errors oddly in Harmony. The Harmony readers don't run the same strict validation, so a bad file surfaces differently there. Re-export from the source.
See In Harmony.
Still stuck¶
Include this in a report and it'll be diagnosed much faster:
- Both applications and their versions
- Which direction and which format
- The summary line from the import page, verbatim
- The file itself — it's small, readable JSON, and it's usually enough to find the problem