What causes "jQuery requires a window with a document" in dotnet/AspNetCore.Docs?

Provide a real window via jsdom: const { JSDOM } = require('jsdom'); const dom = new JSDOM(''); const $ = require('jquery')(dom.window);

dotnet/AspNetCore.Docs · error · Error

jQuery requires a window with a document

Error message

jQuery requires a window with a document

What it means

jQuery 2.2.0 ships a UMD wrapper. When loaded under CommonJS (module.exports) and there is no global.document, it exports a factory: `require('jquery')` returns a function expecting a window-like object. If you call that factory with an object lacking a `.document` property, jQuery refuses to initialize and throws. The error guards against a half-built DOM environment.

Source

Thrown at aspnetcore/mvc/controllers/testing/samples/2.x/TestingControllersSample/src/TestingControllersSample/wwwroot/js/jquery-2.2.0.js:29

 *
 * Date: 2016-01-08T20:02Z
 */

(function( global, factory ) {
    
        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 ) {
    
    // Support: Firefox 18+
    // Can't be in strict mode, several libs including ASP.NET trace
    // the stack via arguments.caller.callee and Firefox dies if
    // you try to trace through "use strict" call chains. (#13335)
    //"use strict";
    var arr = [];
    
    var document = window.document;

View on GitHub (pinned to c67a80103a)

Solutions

Provide a real window via jsdom: const { JSDOM } = require('jsdom'); const dom = new JSDOM(''); const $ = require('jquery')(dom.window);
If you only need jQuery's utilities (not DOM), consider cheerio instead, which is Node-native.
Ensure the object you pass has both `document` and `window` set.

Example fix

// before (Node)
const $ = require('jquery')({}); // throws
// after
const { JSDOM } = require('jsdom');
const dom = new JSDOM('<!DOCTYPE html>');
const $ = require('jquery')(dom.window);

Defensive patterns

Strategy: type-guard

Validate before calling

// Before calling the jQuery factory in Node, ensure a window-like object.
function getWindow() {
  if (typeof window !== 'undefined') return window;
  var jsdom = require('jsdom');
  return new jsdom.JSDOM('<!DOCTYPE html>').window;
}
var w = getWindow();
if (!w || !w.document) {
  throw new Error('No DOM environment available for jQuery');
}
var $ = require('jquery')(w);

Type guard

function isWindowLike(w) {
  return w != null && typeof w === 'object' && !!w.document && typeof w.document.createElement === 'function';
}

Try / catch

try {
  var $ = require('jquery')(providedWindow);
} catch (e) {
  if (/window with a document/.test(e.message)) {
    var { JSDOM } = require('jsdom');
    $ = require('jquery')(new JSDOM('').window);
  } else { throw e; }
}

Prevention

In Node, always pair jQuery with jsdom and pass dom.window.
For pure HTML parsing in Node prefer cheerio.
Never call the factory with an empty object or a DOM Element instead of a window.

When it happens

Trigger: `require('jquery')` in Node.js without jsdom, then calling the returned factory with {} or a non-window object; SSR frameworks that forget to pass jsdom's window; passing a detached Element instead of a window.

Common situations: Server-side rendering of jQuery-dependent code; unit-testing jQuery selectors in Node; Electron main process; migrating from jsdom to a lighter DOM shim that omits `document`.

Related errors

AI-assisted analysis of dotnet/AspNetCore.Docs@c67a80103a (2026-08-13). Data as JSON: /api/errors/99d32dfa1cab9e8d. Report an issue: GitHub.