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 lets you set global default options (ignore/include/copy arrays). toJS validates that defaultOptions().ignore is an array; if a caller set it to a string or object, mapping would misbehave, so it throws on the next toJS/fromJS call. This catches misconfiguration early.

Source

Thrown at aspnetcore/mvc/controllers/testing/samples/2.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. Set ignore as an array: ko.mapping.defaultOptions().ignore = ['name', 'id'];
2. When building dynamically, ensure the variable is an array before assigning.
3. Check the other default options (include, copy) at the same time — they are validated next.

Example fix

// before
ko.mapping.defaultOptions().ignore = 'internalId';
// after
ko.mapping.defaultOptions().ignore = ['internalId'];

// Enforce array shape for defaultOptions().ignore at config time.
function setIgnoreList(keys) {
  if (!Array.isArray(keys)) {
    throw new TypeError('ignore list must be an array, got ' + typeof keys);
  }
  ko.mapping.defaultOptions().ignore = keys;
}

function isStringArray(x) { return Array.isArray(x) && x.every(function (k) { return typeof k === 'string'; }); }

try {
  ko.mapping.toJS(viewModel);
} catch (e) {
  if (/ignore should be an array/.test(e.message)) {
    console.error('Fix defaultOptions().ignore to be an array');
    ko.mapping.defaultOptions().ignore = [];
  } else { throw e; }
}

When it happens

Trigger: ko.mapping.defaultOptions().ignore = 'name'; (string) instead of ['name']; setting it to null; assigning an object.

Common situations: Misreading the API docs; copy-paste from an example that omitted brackets; building the ignore list dynamically and forgetting to wrap in an array.

Related errors

• ko.mapping.defaultOptions().include should be an array.
• When calling ko.fromJS, pass the object you want to convert.
• When calling ko.mapping.toJS, pass the object you want to co
• When calling ko.fromJS, pass the object you want to convert.
• ko.mapping.updateFromJS, use ko.mapping.fromJS instead. Plea

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