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

Call gsap.registerPlugin(GSDevTools) before creating the tool

Please gsap.registerPlugin(GSDevTools)

Error message

Please gsap.registerPlugin(GSDevTools)

What it means

GSDevTools needs the core GSAP library registered before it can initialize. When the constructor runs and the internal core init cannot find a gsap instance, it warns that you must call gsap.registerPlugin(GSDevTools). This registration step hands the tool its GSAP core reference and triggers _initCore().

Source

Thrown at src/GSDevTools.js:369

			}
		}
	},
	_checkIndependence = (animation, vars) => {
		if (!vars.globalSync && animation.parent !== _globalTimeline) { //in case it's nested in a timeline (playing it won't help if the parent timeline isn't playing).
			_globalTimeline.add(animation, _globalTimeline.time());
		}
	},







	GSDevTools = function(vars) {
		if (!_coreInitted) {
			_initCore();
			gsap || console.warn("Please gsap.registerPlugin(GSDevTools)");
		}

		this.vars = vars = vars || {};
		if (vars.animation) {
			(GSDevTools.getByAnimation(vars.animation) || {kill:() => 0}).kill();
		}
		vars.id = vars.id || (_isString(vars.animation) ? vars.animation : _idSeed++); //try to find a unique ID so that sessionStorage can be mapped to it (otherwise, for example, all the embedded codepens on a page would share the same settings). So if no id is defined, see if there's a string-based "animation" defined. Last of all, we default to a numeric counter that we increment.
		_lookup[vars.id + ""] = this;

		("globalSync" in vars) || (vars.globalSync = !vars.animation); //if the user calls create() and passes in an animation AFTER the initial recording time has elapsed, there's a good chance the animation won't be in the recordedRoot, so we change the default globalSync to false because that's the most intuitive behavior.

		//GENERAL/UTILITY
		let _self = this,
			root = _createRootElement(vars.container, vars.minimal, vars.css),
			find = s => root.querySelector(s),
			record = (key, value) => {
				if (vars.persist !== false && _supportsStorage) {
					sessionStorage.setItem("gs-dev-" + key + vars.id, value);

View on GitHub (pinned to 13e2b79054)

Solutions

Call gsap.registerPlugin(GSDevTools) before creating the tool
Ensure gsap core is loaded/imported before GSDevTools
With module imports: import { gsap } from 'gsap'; import { GSDevTools } from 'gsap/GSDevTools'; gsap.registerPlugin(GSDevTools);

Example fix

// before
const devTools = new GSDevTools({ animation: tl });
// after
import { gsap } from 'gsap';
import { GSDevTools } from 'gsap/GSDevTools';
gsap.registerPlugin(GSDevTools);
const devTools = GSDevTools.create({ animation: tl });

Defensive patterns

Strategy: validation

Validate before calling

if (!window.gsap || !gsap.plugins || !gsap.plugins.devTools) { gsap.registerPlugin(GSDevTools); }

Type guard

const isGsapReady = (g) => typeof g === 'object' && g !== null && typeof g.registerPlugin === 'function';

Prevention

Always pair every GSAP plugin import with a gsap.registerPlugin call in the app entry file
Keep GSAP core as the first script/import in load order
Add a dev-mode assertion that gsap is defined before instantiating tools

When it happens

Trigger: Calling new GSDevTools() (or GSDevTools.create()) without ever calling gsap.registerPlugin(GSDevTools), or calling it before gsap is available on window (script load-order issue in non-module environments).

Common situations: Loading GSDevTools.min.js without loading a compatible GSAP core first; forgetting the registerPlugin call after migrating to module imports; using GSDevTools in an environment where window.gsap is not set.

Related errors

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