dotnet/AspNetCore.Docs · error · Error

ko.mapping.defaultOptions().ignore should be an array.

Error message

ko.mapping.defaultOptions().ignore should be an array.

What it means

knockout.mapping.js validates that `defaultOptions().ignore` is an array before processing, throwing if it is not. ignore controls which properties mapping skips; a non-array breaks the array-filtering logic downstream.

Source

Thrown at aspnetcore/mvc/controllers/testing/samples/3.x/TestingControllersSample/src/TestingControllersSample/wwwroot/js/knockout.mapping.js:155

	exports.fromJSON = function (jsonString /*, options, target*/ ) {
		var parsed = ko.utils.parseJson(jsonString);
		arguments[0] = parsed;
		return exports.fromJS.apply(this, arguments);
	};

	exports.updateFromJS = function (viewModel) {
		throw new Error("ko.mapping.updateFromJS, use ko.mapping.fromJS instead. Please note that the order of parameters is different!");
	};

	exports.updateFromJSON = function (viewModel) {
		throw new Error("ko.mapping.updateFromJSON, use ko.mapping.fromJSON instead. Please note that the order of parameters is different!");
	};

	exports.toJS = function (rootObject, options) {
		if (!defaultOptions) exports.resetDefaultOptions();

		if (arguments.length == 0) throw new Error("When calling ko.mapping.toJS, pass the object you want to convert.");
		if (exports.getType(defaultOptions.ignore) !== "array") throw new Error("ko.mapping.defaultOptions().ignore should be an array.");
		if (exports.getType(defaultOptions.include) !== "array") throw new Error("ko.mapping.defaultOptions().include should be an array.");
		if (exports.getType(defaultOptions.copy) !== "array") throw new Error("ko.mapping.defaultOptions().copy should be an array.");

		// Merge in the options used in fromJS
		options = fillOptions(options, rootObject[mappingProperty]);

		// We just unwrap everything at every level in the object graph
		return exports.visitModel(rootObject, function (x) {
			return ko.utils.unwrapObservable(x)
		}, options);
	};

	exports.toJSON = function (rootObject, options) {
		var plainJavaScriptObject = exports.toJS(rootObject, options);
		return ko.utils.stringifyJson(plainJavaScriptObject);
	};

	exports.defaultOptions = function () {

View on GitHub (pinned to c67a80103a)

Solutions

1. Ensure ignore is an array of property-name strings: `ko.mapping.defaults.ignore = ["id", "_internal"];`.
2. Reset to defaults with `ko.mapping.resetDefaultOptions()` if the state is corrupted.
3. Audit every place that writes to `ko.mapping.defaults` / `defaultOptions()` and confirm each of ignore/include/copy is an array.

Example fix

// before
ko.mapping.defaults.ignore = "id";

// after
ko.mapping.defaults.ignore = ["id"];

function setIgnore(props) {
  if (!Array.isArray(props)) throw new TypeError('ignore must be an array');
  ko.mapping.defaults.ignore = props;
}

function isValidOptionArray(v) {
  return Array.isArray(v) && v.every(x => typeof x === 'string');
}

// Rarely caught — fix config instead. Validate at startup:
if (!Array.isArray(ko.mapping.defaults.ignore)) {
  ko.mapping.resetDefaultOptions();
}

When it happens

Trigger: Setting `ko.mapping.defaults.ignore` (or via defaultOptions) to a non-array value such as a string or object, then calling any mapping function that reads defaultOptions (fromJS, toJS, etc.).

Common situations: Typo like `ignore: "id"` instead of `ignore: ["id"]`; merging options where a scalar overwrote the array; copying config from a tutorial that used the wrong shape.

Related errors

• ko.mapping.defaultOptions().include should be an array.
• ko.mapping.defaultOptions().ignore should be an array.
• ko.mapping.defaultOptions().include should be an array.
• ko.mapping.updateFromJS, use ko.mapping.fromJS instead. Plea
• ko.mapping.updateFromJSON, use ko.mapping.fromJSON instead.

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