What causes "Please gsap.registerPlugin(MotionPathPlugin)" in greensock/GSAP?

Call gsap.registerPlugin(MotionPathPlugin) before creating any motionPath tweens

Please gsap.registerPlugin(MotionPathPlugin)

Error message

Please gsap.registerPlugin(MotionPathPlugin)

What it means

MotionPathPlugin's init requires the module-scoped gsap reference set during registration. If a tween uses motionPath before the plugin was registered with gsap.registerPlugin(MotionPathPlugin), init warns and returns false, so the tween renders without motion-path behavior.

Source

Thrown at src/MotionPathPlugin.js:169

		plugin._props.push(prop);
	},
	_sliceModifier = (start, end) => rawPath => (start || end !== 1) ? sliceRawPath(rawPath, start, end) : rawPath;


export const MotionPathPlugin = {
	version: "3.15.0",
	name: "motionPath",
	register(core, Plugin, propTween) {
		gsap = core;
		_getUnit = gsap.utils.getUnit;
		_toArray = gsap.utils.toArray;
		_getStyleSaver = gsap.core.getStyleSaver;
		_reverting = gsap.core.reverting || function() {};
		PropTween = propTween;
	},
	init(target, vars, tween) {
		if (!gsap) {
			console.warn("Please gsap.registerPlugin(MotionPathPlugin)");
			return false;
		}
		if (!(typeof(vars) === "object" && !vars.style) || !vars.path) {
			vars = {path:vars};
		}
		let rawPaths = [],
			{path, autoRotate, unitX, unitY, x, y} = vars,
			firstObj = path[0],
			slicer = _sliceModifier(vars.start, ("end" in vars) ? vars.end : 1),
			rawPath, p;
		this.rawPaths = rawPaths;
		this.target = target;
		this.tween = tween;
		this.styles = _getStyleSaver && _getStyleSaver(target, "transform");
		if ((this.rotate = (autoRotate || autoRotate === 0))) { //get the rotational data FIRST so that the setTransform() method is called in the correct order in the render() loop - rotation gets set last.
			this.rOffset = parseFloat(autoRotate) || 0;
			this.radians = !!vars.useRadians;
			this.rProp = vars.rotation || "rotation";                       // rotation property

View on GitHub (pinned to 13e2b79054)

Solutions

Call gsap.registerPlugin(MotionPathPlugin) before creating any motionPath tweens
Register synchronously at app entry point before scheduling animations
Verify registration by checking gsap.plugins.motionPath

Example fix

// before
import { gsap } from 'gsap';
import { MotionPathPlugin } from 'gsap/MotionPathPlugin';
gsap.to(el, { motionPath: { path: '#curve' } }); // not registered
// after
import { gsap } from 'gsap';
import { MotionPathPlugin } from 'gsap/MotionPathPlugin';
gsap.registerPlugin(MotionPathPlugin);
gsap.to(el, { motionPath: { path: '#curve' } });

Defensive patterns

Strategy: validation

Validate before calling

if (!gsap.plugins.motionPath) gsap.registerPlugin(MotionPathPlugin);

Type guard

const canTweenMotionPath = () => typeof gsap !== 'undefined' && !!gsap.plugins?.motionPath;

Prevention

Register all plugins synchronously in the app entry point
Avoid creating tweens inside module initializers that may run before registration
Add a shared setup module that registers every plugin used in the project

When it happens

Trigger: gsap.to(el, {motionPath:...}) before gsap.registerPlugin(MotionPathPlugin); dynamically building tweens in code that runs before plugin registration completes; motionPath tween inside a function invoked at import time.

Common situations: Missing registerPlugin after switching to npm/ESM imports; deferred tween creation racing plugin setup; tree-shaken import that never executes registration.

Related errors

AI-assisted analysis of greensock/GSAP@13e2b79054 (2026-08-29). Data as JSON: /api/errors/472f37b902e1a91c. Report an issue: GitHub.