Troubleshooting

Symptoms, what causes them, and what to check.

The tool does not open

Nothing happens when you run the script.

Harmony launches user scripts through a system Python 3.9 on PATH, and 3.10 or newer is silently ignored — no error, no window, nothing. Install Python 3.9 and try again.

The script is not in the Scripts menu.

OctoSceneAssembler.js must sit loose in <version>-scripts/, not in a subfolder, and the Python package must be in a folder named exactly octoSceneAssembler. See Installation.

A tag did nothing

head-Peg gave me a drawing called head-Peg.

A tag must be a whole piece between separators. Peg is not a tag; P is. Write head-P or head=P.

sky-0007 was not read as a depth.

A bare number is deliberately not a tag — sequence files are full of them, and a frame called 0007 must never become a depth instruction. Write Z0.1, 0.5F or 10B.

Part of my name disappeared.

The parser reads tags right to left and stops at the first piece that is not one. If a real word in your name happens to be a valid tag (…-P), use the equals form: two-part-name=P.

Full grammar: Tags.

A folder was not routed

It came in as a plain folder instead of going to its magnet.

Either no magnet matches the name, or the magnet is inactive. OSA says so at import:

'PROPS' magnet is off: 'PROPS' came in as a plain folder, nothing was routed

Check the Magnets section, and remember matching is case-insensitive and tries exact, prefix and suffix — longest match wins. See Magnets.

The Assemble button is grey

The feedback bar has a red message. Red is the only colour that disables the button, and the bar names the blocker. Resolve it and the button comes back.

Frame verbs refuse

Enable 'Split/Merge Frames' checkbox to merge/suck frames

That guard is off by default, in the Browser's Settings section. Structural edits rearrange a plan; frame edits rearrange timing. See Split & Merge.

Merge or Split is greyed out

Hover it — the tooltip says why. Merge needs at least two nodes; Split needs something to split. A greyed entry without a reason is a UI bug, not a rule.

Artwork did not arrive

Read the report. Every refusal has a kind:

Kind	Check
import-failed	the source file still exists and is readable
format-mismatch	the extension lies about the content — a renamed file
element-swap	an Original Bitmap drawing stayed a TVG
utransform	the conversion was refused; often an unsupported source
no-bridge	Harmony is there but the script bridge never opened — restart Harmony

Full list: Assembling.

A vector track vanished in Original Bitmap

It did not vanish — it was not written, and it is still in your tree. Original Bitmap has no art layers, so vector cannot land there. Either switch the drawing to Art Layers, or move that track to a drawing that is. See Original Bitmap.

"Could not auto-save the session to disk"

A yellow, temporary message. The tree is still in memory and Assemble still works — but the crash net is down.

The reason is in the log, and it names the cause:

%APPDATA%/Toon Boom Animation/Toon Boom Harmony Premium/octo_scene_assembler/osa.log

Look for Autosave: could not write the file:. Common causes are a full disk, a locked folder, or an antivirus holding the sessions directory.

The session did not come back

No bar was offered. A session is per scene — a scene saved under a different name has a different session. Also: a successful Restore deletes the session it restored, and Dismiss deletes it on purpose.

The bar said the session was unreadable. Both the file and its one backup failed to parse. OSA tells you rather than starting empty in silence, because being told nothing is how people conclude the autosave never worked.

See Sessions & Crash Recovery.

Harmony crashed during Assemble

Assemble is not a transaction — Harmony accumulates the whole build into one undo, so a crash or a cancel leaves the nodes already created.

Recovery: Harmony's own undo, then fix the tree and assemble again. Your staging tree still describes everything that did not land, because OSA only flattens what landed.

The Node View looks stacked, not laid out

Nodes on top of each other mean the layout pass did not run — check the report for a phase-error. The Wide Bus places every node, so a pile is a failure, not a style.

Reporting a bug

? → About has the three things a report needs: version, licence state and Machine ID.

Attach osa.log. It is how support reads what your Harmony did without needing your scene.