Errors and diagnostics#

Marionette reports invalid framework configuration with MarionetteError. Inspect the error's code to identify the contract, then read the matching diagnostic from the installed version. Application failures, such as a rejected API request, can remain ordinary errors handled by the application that owns that work.

MarionetteError#

Import MarionetteError from marionette or @mnjs/utils; within the same module format they export the same constructor. Use new MarionetteError(options). Each call creates a native Error instance with a stack; instanceof Error and instanceof MarionetteError both work. Calling it as a plain function is unsupported.

import { MarionetteError } from 'marionette';

const error = new MarionetteError({
  code: 'MN0019',
  message: 'The configured handler must resolve to a function.'
});
const diagnosticCode = error.code;
const description = error.toString();

The example constructs an error for inspection. Framework operations create their own errors; do not use Marionette's MN codes for unrelated application failures.

Only the listed metadata fields (code, description, fileName, lineNumber, name, message, number, url) are copied from options. They become ordinary own fields; other option fields are ignored. Values are preserved rather than validated or coerced. Construction and formatting are synchronous, with no ownership or cleanup lifecycle. Extend the constructor with native class extends when a distinct application error type is useful.

Find a diagnostic#

Use the package's local documentation helper from the application's directory. Replace <skill> with the installed or copied skills/marionette directory:

node <skill>/scripts/docs.mjs --diagnostic MN0019

The result includes the installed version, code status, affected objects, remediation, diagnostic URL, and docsSection. Read that section with --section to stay inside the installed documentation. Retired codes remain discoverable, but are no longer emitted by that release. Follow the installed contract before changing code: the website can describe a different release. Unknown codes are not evidence of a framework bug; first check which package/version produced the error.

Diagnostics identify invalid inputs and configuration. They do not replace application error handling, and they do not catch every possible misuse. Synchronous callback exceptions propagate through dispatch. An Application's asynchronous preparation rejection is part of its start lifecycle; handle failure at the owning workflow boundary.

MN0001#

view-el-must-be-dom-element. Status: retired. Applies to CollectionView, View.

Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.

MN0002#

region-el-type-invalid. Status: retired. Applies to Region.

Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.

MN0003#

view-already-owned. Status: active. Applies to Application, CollectionView, Region, View.

Use the owning Application to display its prepared root. Detach a displayed view from its Region or CollectionView before adopting it elsewhere, or create a new view instance.

MN0004#

region-el-required. Status: active. Applies to Region.

Configure the Region with an el selector or DOM element before using it.

MN0005#

region-el-not-found. Status: active. Applies to Region.

Render the parent View before direct selector-backed Region operations, ensure the selector resolves within its parent element, or explicitly allow a missing element where supported.

MN0006#

region-view-required. Status: retired. Applies to Region.

Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.

MN0007#

region-view-destroyed. Status: active. Applies to Application, Region, View.

Create a new View instance instead of attempting to show a destroyed view.

MN0008#

region-definition-invalid. Status: retired. Applies to Application, Region, View.

Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.

MN0009#

event-bindings-invalid. Status: retired. Applies to Application, Behavior, CollectionView, MnObject, Region, View.

Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.

MN0010#

request-bindings-invalid. Status: retired. Applies to Application, Behavior, CollectionView, MnObject, Region, View.

Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.

MN0011#

collection-view-child-view-required. Status: active. Applies to CollectionView.

Configure childView with a View class or a function that returns a View class.

MN0012#

collection-view-child-view-invalid. Status: retired. Applies to CollectionView.

Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.

MN0013#

collection-view-container-not-found. Status: active. Applies to CollectionView.

Ensure childViewContainer resolves to an element within the rendered CollectionView.

MN0014#

collection-view-filter-invalid. Status: retired. Applies to CollectionView.

Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.

MN0015#

collection-view-swap-non-children. Status: active. Applies to CollectionView.

Pass two views currently owned by the CollectionView to swapChildViews.

MN0016#

behavior-definition-invalid. Status: retired. Applies to Behavior, CollectionView, View.

Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.

MN0017#

radio-channel-name-required. Status: active. Applies to Radio.

Pass a non-empty channel name when creating or accessing a Radio channel.

MN0018#

ui-reference-invalid. Status: active. Applies to Behavior, CollectionView, View.

Use @ui.<name> with a non-empty own key whose value is a string selector, or replace the reference with a literal selector.

MN0019#

handler-not-callable. Status: active. Applies to Application, Behavior, CollectionView, MnObject, Region, View.

Provide a function or the string name of a callable method on the binding context.

MN0020#

named-region-not-found. Status: active. Applies to View.

Define the named Region before using child-View or Region-removal operations, or use getRegion or hasRegion for optional lookup.

MN0021#

radio-channel-not-found. Status: active. Applies to Radio.

Create the named channel with Radio.channel(name) before resetting it, or call Radio.reset() with no arguments to reset all existing channels.

MN0022#

collection-view-empty-view-invalid. Status: retired. Applies to CollectionView.

Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.

MN0023#

ui-elements-unavailable. Status: active. Applies to Behavior, CollectionView, View.

Declare a ui map, then render the View or explicitly bind its UI elements before calling getUI; bind them again before calling getUI after unbinding.

MN0024#

child-container-argument-invalid. Status: active. Applies to CollectionView.

Pass nonnegative integer counts. Reducing an empty child container requires an initial value.

MN0025#

child-container-method-not-callable. Status: retired. Applies to CollectionView.

Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.

MN0026#

entity-event-name-unsafe. Status: active. Applies to Application, Behavior, CollectionView, MnObject, Region, View.

Rename an own proto entry in an entity-event map before binding or selectively unbinding it.

MN0027#

feature-name-invalid. Status: retired. Applies to Behavior, CollectionView, View.

The v5 feature registry is removed. Configure child event prefixes per View, trigger behavior per trigger, and application values through State or explicit configuration.

MN0028#

region-destroyed-operation. Status: retired. Applies to Region.

Calls to show, empty, or reset after Region destruction are lifecycle-safe no-ops. Use a live Region when the operation must take effect.

MN0029#

view-destroyed-set-element. Status: retired. Applies to CollectionView, View.

Calls to setElement after View or CollectionView destruction begins are lifecycle-safe no-ops. Use a live instance when element replacement must take effect.

MN0030#

region-registration-conflict. Status: active. Applies to Region, View.

Register a live, unowned Region under an unused name; remove an existing named Region before replacing it and use a fresh Region instance for a different owner.

MN0031#

application-registration-conflict. Status: active. Applies to Application.

Register a live, unowned Application instance under an unused non-empty string name; use hasChildApp before constructing a dynamic child when allocation must be avoided.

MN0032#

region-name-invalid. Status: active. Applies to View.

Pass a non-empty string name to a named Region operation.

MN0033#

merge-options-keys-invalid. Status: retired. Applies to Application, Behavior, CollectionView, MnObject, Region, View.

Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.

MN0034#

state-key-invalid. Status: retired. Applies to StateApi.

The concrete v5 alpha State key validation is removed. Use the selected source's native key contract.

MN0035#

state-ownership-conflict. Status: retired. Applies to Behavior, CollectionView, MnObject, View.

The concrete v5 alpha State ownership rule is removed. Supplied sources are borrowed and may be shared by multiple owners; createState results are owned and disposed by their owner.

MN0036#

event-delegator-contract-invalid. Status: retired. Applies to Behavior, CollectionView, View.

Use the documented argument types. Marionette no longer emits a dedicated runtime diagnostic for this unsupported input shape.

MN0037#

adapter-observation-unsupported. Status: active. Applies to Application, Behavior, CollectionView, MnObject, View.

Configure a StateApi or DataApi that can observe the selected source, or remove the declarative event map.

MN0038#

adapter-cleanup-invalid. Status: retired. Applies to Application, Behavior, CollectionView, MnObject, View.

DataApi and StateApi adapters must return cleanup functions. Core no longer wraps or validates cleanup on each registration.

MN0039#

collection-data-contract-invalid. Status: active. Applies to CollectionView.

Return an ordered array with unique stable keys and emit a valid reorder, reset, or update structural record.

MN0040#

private-framework-member-access. Status: active. Applies to Application, Behavior, CollectionView, MnObject, Region, View.

Use the documented public Marionette API instead of reading or calling this private framework member.