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

Pass a jsdom window: require('jquery')(new (require('jsdom').JSDOM)('').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

Identical guard to error 2 in the 3.x sample's jquery-2.2.0.js: the UMD CommonJS factory requires a window with a `.document` property. Calling it with a non-window object throws.

Source

Thrown at aspnetcore/mvc/controllers/testing/samples/3.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

Pass a jsdom window: require('jquery')(new (require('jsdom').JSDOM)('').window).
Use cheerio for non-DOM jQuery-style parsing in Node.
Ensure the passed object exposes both `document` and `window`.

Example fix

// before
const $ = require('jquery')({}); // throws
// after
const { JSDOM } = require('jsdom');
const $ = require('jquery')(new JSDOM('').window);

Defensive patterns

Strategy: type-guard

Validate before calling

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 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

Pair jQuery with jsdom in Node; pass dom.window.
Use cheerio for pure HTML parsing.
Never pass an empty object or DOM Element instead of a window.

When it happens

Trigger: `require('jquery')` in Node without jsdom and invoking the factory with a non-window; SSR without a DOM shim.

Common situations: Server-side rendering; Node unit tests; Electron main process.

Related errors

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