After Effects MCP script errors

This page covers every error a script can return: what After Effects raises while it runs, what Prism's gate raises before it runs, and results that never arrived. Read the errorType first: it says whether anything ran. Every error here shows in your AI client, not the panel.

Runtime errors: the script reached After Effects

A runtime error carries line and sourceText, both pointing at your source (ignore compiledLine); Prism appends nothing to the message. It may end with "Committed before the failure: {n} project item(s) added; {n} layer(s) added ({names}); these persist (the undo group does not auto-revert on error) — inspect the project before re-running." A Spanish After Effects returns "null no es un objeto" for the first entry; the fix is the same.

Object was null

You see: "null is not an object" or "undefined is not an object"

Meaning. The script read a member of something that does not exist, like a missing comp or layer. It stopped there.

Fix. Check the object exists before using it, for example if (comp).

Do not resend the script unchanged; the same null waits on the same line.

Object no longer valid

You see: "Object is invalid"

Meaning. The script used a comp, layer or item that After Effects has since removed or replaced. It stopped there.

Fix. Find the item again by id or name in a new call.

Footage item missing

You see: "AVItem is undefined" or "Function path.setValue is undefined"

Meaning. The script called a footage or comp function on something that is not one. It stopped there.

Fix. Check the item is footage or a comp before calling it.

Nesting too deep

You see: "Stack overrun"

Meaning. The script nests more than After Effects can hold, about 90 conditionals or 150 brackets. It stopped there.

Fix. Flatten the expression: use a lookup object, named variables, or a loop.

Number result invalid

You see: "invalid numeric result (divide by zero?)"

Meaning. A value had the wrong number of parts, or an array was joined into text. It stopped there.

Fix. Return the property's exact dimension count, and index arrays instead of joining them.

Helper failed

You see: "prism.{fn}: {msg} — thrown inside the prism SDK helper, not at the reported line; check the arguments you passed to prism.{fn}()."

Meaning. The error came from inside a Prism helper, not your line. The arguments you passed are the usual cause.

Fix. Check the arguments at your prism.* call, then run it again.

Where a helper failed

You see: "this error was thrown inside the prism SDK helper (prism-sdk.ts line {n}), not at a line of your script — …" What it means. The failing line is inside Prism's own helpers, so source reads "(inside the prism SDK — not your code)" and the hint names the case. Do this.

1. If your script calls prism.*: "the cause is almost always the arguments you passed to the prism.* call; check them at your call site."
2. If it does not: "your script makes no prism.* call, so this is NOT something to fix in your code. The SDK failed while loading or running. Retry once; if it repeats, report it with prism_support({action:"report", type:"bug"})".
3. The registered-helper variant, "this error was thrown inside your registered project prelude module "{name}"", means fix the module and re-register it.

The gate: the script never ran

The gate is deterministic: an identical script gets an identical rejection, so do not resend one unchanged. Line numbers are yours.

Script too large · script-too-large

You see: "Script is {n} characters, which is over the 100,000 character limit After Effects can receive in one call."

Meaning. The script is {n} characters. One call takes at most 100,000. Nothing ran.

Fix. Split the work into smaller asks, or register the repeated helpers once.

Script failed the check · type-error

You see: "TypeScript gate: the script does not type-check against the AE + Prism SDK types."

Meaning. The script did not pass Prism's check. Nothing ran. The listed lines name each problem.

Fix. Edit the listed lines, then send the script again.

If a name seems missing rather than misspelled, ask the agent to look for a tool that does it, or register the helper once. Optional values (app.project.file, a stroke, a layer source) can be null.

Script failed the check · type-error

You see: "Script rejected: {name} does not exist in ExtendScript — After Effects runs an ES3 engine, and Prism only shims the Array iteration methods, String.trim and Object.keys/values/entries."

Meaning. The script did not pass Prism's check. Nothing ran. The listed lines name each problem.

Fix. Edit the listed lines, then send the script again.

Async not supported · banned-feature

You see: "async/await cannot run in After Effects — ExtendScript is fully synchronous with no event loop…"

Meaning. The script uses async or await. After Effects runs everything in order, with no waiting. Nothing ran.

Fix. Remove async and await; call the work directly in sequence.

Script not valid · parse-error

You see: "Script is not valid JavaScript/TypeScript: {codeFrame}"

Meaning. The script has a syntax error at the marked position. Nothing ran.

Fix. Fix the syntax at the marked line, then send it again.

Prism could not run it · transpile-gate

You see: "Compiled output failed the ES3 gate: {violation} — this is a Prism compiler-envelope gap; rewrite the construct in simpler form and report via the feedback tool."

Meaning. A final check refused the script. This is a gap in Prism, not your script. Nothing ran.

Fix. Rewrite the construct the message names in a simpler form, then report it.

Undo group in script

You see: "Script rejected: do not call app.beginUndoGroup/endUndoGroup — Prism already wraps every execution in ONE undo group (name it with the undoGroup arg)."

Meaning. The script opens its own undo group. Prism already wraps every run in one. Nothing ran.

Fix. Remove app.beginUndoGroup and app.endUndoGroup; name the group with the undoGroup argument.

Results that did not arrive

No result returned

You see: "Script produced no result envelope (result is null)."

Meaning. The script finished but returned nothing, so Prism cannot say what it did.

Fix. End the script with a top-level JSON.stringify({status:"success", …}).

Still running

You see: "After Effects did not respond within {N}s, but the script is almost certainly STILL RUNNING or already COMPLETED in the panel."

Meaning. After Effects has not answered after N seconds. The scene build is probably still running or already done.

Fix. Wait, then check recent results. Do not run it again; that duplicates the work.

Connection dropped

You see: "The bridge to After Effects dropped while this call was in flight."

Meaning. The connection to Prism dropped. Prism reconnects on its own. Work already sent to After Effects may still finish.

Fix. Wait 10 seconds, then check recent results. Do not run it again.

Outcome unknown · ambiguous-outcome

You see: "This script already ran in After Effects and its result was lost on the way back, so Prism cannot say whether it finished. It was NOT run again — re-running could duplicate whatever it created."

Meaning. This work already ran, but its result was lost. It was not run again, so the project may have changed.

Fix. Check what landed in the project, then continue from there. Do not run it again.

Registered helpers after a server restart

What it means. Helpers you registered live per connection. After a server restart or a new connection, a script that calls one fails on the missing name; Prism's own helpers come back on their own, yours do not. Do this. Register the helpers again; the module list in the message shows what is registered.

Other script states

Batch entry invalid

You see: "Batch script #{n} rejected: each entry must be a script string o…"

Meaning. Batch script {n} is not a script string or a script with a label. Nothing ran.

Fix. Pass each entry as a string or \{script, label\}.

Module name invalid

You see: "prelude.register.name must be a short identifier — a letter fol…"

Meaning. The module name is not a short identifier. Nothing was registered.

Fix. Use a letter followed by letters, digits, _ or -, at most 64 characters.

Module source empty

You see: "prelude.register.source must be a non-empty TypeScript / modern…"

Meaning. The module has no source, or it returns at the top level. Nothing was registered.

Fix. Define functions and constants at the top level, with no top-level return.

Module too large

You see: "prelude module "{name}" source is {n} bytes — over the {limit}…"

Meaning. The module is {bytes} bytes, over the per-module limit. Nothing was registered.

Fix. Split it into smaller modules.

Script syntax unsupported · pre-check

You see: "ES3 error: {rules}…"

Meaning. The script uses syntax After Effects cannot run, or a dialog call that would freeze it. Nothing ran.

Fix. Apply each change the message lists, such as var instead of let.

Empty error thrown

You see: "Script threw an empty error (e.g. throw "") — add a message at…"

Meaning. The script threw an error with no message, so nothing more is known.

Fix. Add a message at the throw site, then run it again.

Script refused by After Effects

Meaning. After Effects could not read the script Prism sent. Nothing ran. This is a gap in Prism.

Fix. Wrap nested conditionals in parentheses or use if/else, then report it.

Return outside function

You see: "Illegal 'return' outside of a function body…"

Meaning. The script returns at the top level, which After Effects does not allow. Nothing ran.

Fix. End the script with a value instead of return.

Helpers not loaded · __PRISM_NEED_PRELUDE__

You see: "PRISM_NEED_PRELUDE…"

Meaning. After Effects has not loaded Prism's helpers yet. Prism sends them and runs the script again.

Fix. Nothing to do. If it repeats, reopen the panel.

Project not open

You see: "project missing…"

Meaning. After Effects has no project open, so the script has nothing to work on. Nothing changed.

Fix. Open or create a project in After Effects, then run it again.

Module failed

You see: "(inside your registered prelude module "{name}" — not your scri…"

Meaning. The error came from inside your registered module "{name}", not this script.

Fix. Fix the module, register it again, then run the script.

Colour not recognised

You see: "malformed hex color "#{hex}" — use "#rgb", "#rrggbb" or "#rrgg…"

Meaning. The colour value is not in a form Prism accepts. Nothing changed.

Fix. Use #rrggbb, [r,g,b] from 0 to 1, rgb(255,128,0), or a CSS name.

Layer not a shape

You see: "prism.shape: layer "{n}" is not a ShapeLayer (it has no "ADBE R…"

Meaning. "{name}" is not a shape layer, so its contents cannot be edited. Nothing changed.

Fix. Target a shape layer.

Shape group not found

You see: "prism.shape: "{seg}" not found under "{grp}" on layer "{n}". G…"

Meaning. No group "{seg}" exists under "{grp}" on that layer. Nothing changed.

Fix. Use a group name from the list, and re-resolve after adding siblings.

Footage file empty

You see: "prism.importFootage: file is empty (0 bytes): {fsName} — likely…"

Meaning. The file is 0 bytes, usually a cloud-sync placeholder. Nothing was imported.

Fix. Download the file locally, then import it again.

Import not ready

You see: "prism.importFootage: imported "{fsName}" but could not re-find…"

Meaning. The file was imported but After Effects cannot read it back yet.

Fix. Run the import again in a new call.

Source swap failed

You see: "prism.replaceSource: swap did NOT verify — layer "{n}" source…"

Meaning. The layer's source was not replaced, or the item id does not exist. Nothing changed.

Fix. Import the footage first, then replace the source in a new call.

Parent is animated

You see: "parent: "{target}" is ANIMATED — {props}. Parenting preserves…"

Meaning. The parent layer moves, so the child would inherit that motion at every other time. Nothing changed.

Fix. Attach to a still parent, or bake the parent's transform first.

Checkpoint not saved

You see: "prism.checkpoint: the backup did NOT get written — "{dst}" exis…"

Meaning. The backup file was not written, so no checkpoint exists. Nothing was rolled back.

Fix. Check free disk space and that the checkpoints folder is writable, then save again.

Option not recognised

You see: "{door}: unknown {enumName} "{w}". Use one of: {words}…"

Meaning. "{w}" is not one of the options for {enumName}. Nothing changed.

Fix. Use one of the options the message lists.

Matte or mask invalid

You see: "prism.mode.matte: "{n}" cannot be its own track matte.…"

Meaning. A layer cannot be its own matte, or the mask index is out of range. Nothing changed.

Fix. Pick another matte layer, or a mask index from 1 to the count.

Camera rig missing

You see: "camera.move: no rig in this comp — call prism.camera.rig(comp,…"

Meaning. This composition has no camera rig, so the camera cannot be moved or reset. Nothing changed.

Fix. Build the rig first, then move the camera.

Tracker needs footage

You see: "prism.seedTracker: a footage/precomp AV Layer is required…"

Meaning. Motion trackers only work on footage or precomp layers. Nothing changed.

Fix. Target a footage or precomp layer.

Wrong object passed

You see: "{door}: {role} is required — get a layer with comp.layer(index)…"

Meaning. A helper received the wrong kind of object, such as a name instead of a layer. Nothing changed.

Fix. Pass the object the message names, for example comp.layer(index).

Common questions

If an entry here does not match, email support@oneprism.io with the panel version (footer, "After Effects MCP v…") and the Copy diagnostic from the panel's Support section. On panel 1.5.1 the Support section may be empty; the version plus the error text is enough.

Related