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

Call gsap.registerPlugin(Observer) before creating any Observer

Please gsap.registerPlugin(Observer)

Error message

Please gsap.registerPlugin(Observer)

What it means

Observer is a registered GSAP plugin; its init() checks _coreInitted and warns if gsap.registerPlugin(Observer) was never called, because core hooks (context, ticker, etc.) were not installed. The Observer still continues initializing in most builds, but without registration behavior may be broken.

Source

Thrown at src/Observer.js:153

			_isTouch = Observer.isTouch = _win.matchMedia && _win.matchMedia("(hover: none), (pointer: coarse)").matches ? 1 : ("ontouchstart" in _win || navigator.maxTouchPoints > 0 || navigator.msMaxTouchPoints > 0) ? 2 : 0;
			_eventTypes = Observer.eventTypes = ("ontouchstart" in _docEl ? "touchstart,touchmove,touchcancel,touchend" : !("onpointerdown" in _docEl) ? "mousedown,mousemove,mouseup,mouseup" : "pointerdown,pointermove,pointercancel,pointerup").split(",");
			setTimeout(() => _startup = 0, 500);
			_coreInitted = 1;
		}
		ScrollTrigger || _setScrollTrigger(); // Observer might be initted BEFORE ScrollTrigger, so don't put this with the initting code. ScrollTrigger will call Observer.register() when it inits.
		return _coreInitted;
	};

_horizontal.op = _vertical;
_scrollers.cache = 0;

export class Observer {
	constructor(vars) {
		this.init(vars);
	}

	init(vars) {
		_coreInitted || _initCore(gsap) || console.warn("Please gsap.registerPlugin(Observer)");
		ScrollTrigger || _setScrollTrigger();
		let {tolerance, dragMinimum, type, target, lineHeight, debounce, preventDefault, onStop, onStopDelay, ignore, wheelSpeed, event, onDragStart, onDragEnd, onDrag, onPress, onRelease, onRight, onLeft, onUp, onDown, onChangeX, onChangeY, onChange, onToggleX, onToggleY, onHover, onHoverEnd, onMove, ignoreCheck, isNormalizer, onGestureStart, onGestureEnd, onWheel, onEnable, onDisable, onClick, scrollSpeed, capture, allowClicks, lockAxis, onLockAxis} = vars;
		this.target = target = _getTarget(target) || _docEl;
		this.vars = vars;
		ignore && (ignore = gsap.utils.toArray(ignore));
		tolerance = tolerance || 1e-9;
		dragMinimum = dragMinimum || 0;
		wheelSpeed = wheelSpeed || 1;
		scrollSpeed = scrollSpeed || 1;
		type = type || "wheel,touch,pointer";
		debounce = debounce !== false;
		lineHeight || (lineHeight = parseFloat(_win.getComputedStyle(_body).lineHeight) || 22); // note: browser may report "normal", so default to 22.
		let id, onStopDelayedCall, dragged, moved, wheeled, locked, axis,
			self = this,
			prevDeltaX = 0,
			prevDeltaY = 0,
			passive = vars.passive || (!preventDefault && vars.passive !== false),
			scrollFuncX = _getScrollFunc(target, _horizontal),

View on GitHub (pinned to 13e2b79054)

Solutions

Call gsap.registerPlugin(Observer) before creating any Observer
Use the side-effect import: import "gsap/Observer" plus import { Observer } from "gsap/Observer" and register explicitly
Register all used plugins in a single bootstrap module imported first
If using CDN, load Observer.js after gsap.min.js and call registerPlugin

Example fix

// before
import { Observer } from 'gsap/Observer';
Observer.create({ onY: y => console.log(y) });
// after
import { gsap, Observer } from 'gsap/all';
gsap.registerPlugin(Observer);
Observer.create({ onY: y => console.log(y) });

Defensive patterns

Strategy: validation

Validate before calling

import { gsap, Observer } from 'gsap/all';
if (!gsap.core.globals().Observer) gsap.registerPlugin(Observer);

Try / catch

try {
  const obs = Observer.create(vars);
} catch (e) {
  gsap.registerPlugin(Observer);
  const obs = Observer.create(vars);
}

Prevention

Register every plugin in one bootstrap module imported first
Never rely on side-effect-only imports; register explicitly
Lint for Observer usage without registerPlugin

When it happens

Trigger: Calling new Observer(...) or Observer.create(...) without a prior gsap.registerPlugin(Observer) — typically when loading GSAP core and Observer as separate modules and forgetting registration, or importing Observer without importing its side-effect registration.

Common situations: Bundler setups where tree-shaking removed the registration side effect, mixing CDN and npm imports, or calling Observer before registerPlugin runs due to module import order.

Related errors

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