OrchardCMS/OrchardCore · error · Error

jQuery requires a window with a document

Error message

jQuery requires a window with a document

What it means

jQuery 3.6.0's UMD wrapper throws this when loaded where a 'window' with a 'document' cannot be provided. As in 3.5.1, module loaders get a factory expecting a window argument; calling it without a valid document aborts initialization.

Solutions

  1. Ensure a DOM exists before import: use jsdom and require('jquery')(dom.window), or set testEnvironment: 'jsdom' in Jest.
  2. Import the official 'jquery' npm package (3.6.0) rather than the vendored wwwroot copy in non-browser code.
  3. Verify bundler target/env is 'web'/'browser' when shipping jquery.js so it executes only where window exists.
  4. If intentionally headless, do not load jQuery there; use fetch/DOM-free utilities instead.

Example fix

// before
const $ = require('./Vendor/jquery-3.6.0/jquery.js'); // throws
// after
const { JSDOM } = require('jsdom');
const $ = require('jquery')(new JSDOM('<html></html>').window);
Defensive patterns

Strategy: validation

Validate before calling

if (typeof window === 'undefined' || !window.document) {
  const { JSDOM } = require('jsdom');
  const dom = new JSDOM('');
  global.window = dom.window; global.document = dom.window.document;
}
const $ = require('jquery');

Type guard

function domAvailable() { return typeof window !== 'undefined' && window.document !== null; }

Try / catch

try { const $ = require('./Vendor/jquery-3.6.0/jquery.js'); } catch (e) { if (e.message.includes('window with a document')) { bootstrapJsdom(); } else { throw e; } }

Prevention

When it happens

Trigger: Requiring the 3.6.0 vendored build under Node.js/SSR/tests without jsdom; running it in a worker or sandboxed vm; invoking module.exports(windowLike) with an object missing 'document'.

Common situations: After upgrading 3.5.1 → 3.6.0, existing Node-side imports that 'worked' with polyfills fail if the polyfill no longer sets global.document; bundler environment misconfiguration (target: node) pulling the browser file.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

AI-assisted analysis of OrchardCMS/OrchardCore@4306c0717f (2026-09-13). Data as JSON: /api/errors/e7c96e340b06d058. Report an issue: GitHub.

Appendix: source

Thrown at src/OrchardCore.Modules/OrchardCore.Resources/wwwroot/Vendor/jquery-3.6.0/jquery.js:31

 */
( function( global, factory ) {

	"use strict";

	if ( typeof module === "object" && typeof module.exports === "object" ) {

		// For CommonJS and CommonJS-like environments where a proper `window`
		// is present, execute the factory and get jQuery.
		// For environments that do not have a `window` with a `document`
		// (such as Node.js), expose a factory as module.exports.
		// This accentuates the need for the creation of a real `window`.
		// e.g. var jQuery = require("jquery")(window);
		// See ticket #14549 for more info.
		module.exports = global.document ?
			factory( global, true ) :
			function( w ) {
				if ( !w.document ) {
					throw new Error( "jQuery requires a window with a document" );
				}
				return factory( w );
			};
	} else {
		factory( global );
	}

// Pass this if window is not defined yet
} )( typeof window !== "undefined" ? window : this, function( window, noGlobal ) {

// Edge <= 12 - 13+, Firefox <=18 - 45+, IE 10 - 11, Safari 5.1 - 9+, iOS 6 - 9.1
// throw exceptions when non-strict code (e.g., ASP.NET 4.5) accesses strict mode
// arguments.callee.caller (trac-13335). But as of jQuery 3.0 (2016), strict mode should be common
// enough that all such attempts are guarded in a try block.
"use strict";

var arr = [];

View on GitHub (pinned to 4306c0717f)