These supplemental examples are checked against the published beta.1 and current development candidate. API references identify their library source.
# Troubleshoot an application
Start with the installed package's documentation and a small reproduction. An npm
version identifies a published release; an unpublished candidate also needs its
source commit. [The development starter](/development.md) keeps these together.
| Symptom | Check first | Contract |
| --- | --- | --- |
| An import or method in an example is missing | Compare the installed manifest with the example's source revision. Use all five matching tarballs for a development candidate. | [Installation](https://github.com/marionettejs/marionette/blob/9404b1935b855e05c982f697d8471764a140e8f6/docs/installation.md), [public exports](https://github.com/marionettejs/marionette/blob/9404b1935b855e05c982f697d8471764a140e8f6/docs/public-api.md) |
| TypeScript loses option or state inference | Type `initialize` options and `createState`'s return value; use the generated package declarations. Run the starter's strict typecheck. | [TypeScript](https://github.com/marionettejs/marionette/blob/9404b1935b855e05c982f697d8471764a140e8f6/docs/typescript.md) |
| Nothing appears in a Region | Verify its element exists within the parent; render the parent before direct Region operations. | [Region](https://github.com/marionettejs/marionette/blob/9404b1935b855e05c982f697d8471764a140e8f6/docs/marionette.region.md) |
| A model changes but the UI does not | Configure an observing DataApi or StateApi, declare the matching event map, and update the DOM in its handler. Mutating a plain object does not emit an event. | [DataApi](https://github.com/marionettejs/marionette/blob/9404b1935b855e05c982f697d8471764a140e8f6/docs/data.api.md), [state sources](https://github.com/marionettejs/marionette/blob/9404b1935b855e05c982f697d8471764a140e8f6/docs/marionette.state.md) |
| A draft or focus disappears when a list changes | Keep stable unique keys and surviving child Views. Avoid rendering the whole parent to update one row. | [CollectionView](https://github.com/marionettejs/marionette/blob/9404b1935b855e05c982f697d8471764a140e8f6/docs/marionette.collectionview.md), [forms](https://github.com/marionettejs/marionette/blob/9404b1935b855e05c982f697d8471764a140e8f6/docs/forms-and-accessibility.md) |
| An old request replaces the selected screen | Give navigation a cancellation owner and reject stale completion before committing. | [Routing](https://github.com/marionettejs/marionette/blob/9404b1935b855e05c982f697d8471764a140e8f6/docs/routing.md), [Application](https://github.com/marionettejs/marionette/blob/9404b1935b855e05c982f697d8471764a140e8f6/docs/marionette.application.md) |
| Click handlers multiply after editing a module | Destroy the previous owner in HMR disposal; release application listeners too. The starter demonstrates this boundary. | [Development](/development.md), [lifecycle](https://github.com/marionettejs/marionette/blob/9404b1935b855e05c982f697d8471764a140e8f6/docs/view.lifecycle.md) |
| A stack frame points to bundled JavaScript | Enable source maps and retain dependency maps in the bundler. The starter config does both. | [Debug authored source](/development.md#debug-the-authored-source) |
## Follow a diagnostic code
Framework errors expose stable `MNxxxx` codes and a documentation URL. Match the
code, rather than exact error prose. The [diagnostic catalog](https://github.com/marionettejs/marionette/blob/9404b1935b855e05c982f697d8471764a140e8f6/docs/diagnostic-catalog.md)
records active and retired codes. The examples below reproduce common failures
and show separate corrected operations. They are executed against installed
packages by the documentation fixture.
### MN0020: define the named Region
An element in a template does not register a Region. In a browser module:
```javascript
import { View } from 'marionette';
const missing = new View({ template: () => '' });
missing.render();
export function fail() { missing.detachChildView('detail'); }
export function fix() {
const layout = new View({
template: () => '',
regions: { detail: 'section' }
});
layout.showChildView('detail', new View({ template: () => 'Ready' }));
const result = layout.el.textContent;
layout.destroy();
return result;
}
export function cleanup() { missing.destroy(); }
```
`fail()` throws MN0020. `fix()` returns `Ready` after displaying a child in the
registered Region. For optional lookup, use `hasRegion` or `getRegion` before an
operation. See [named Regions](https://github.com/marionettejs/marionette/blob/9404b1935b855e05c982f697d8471764a140e8f6/docs/marionette.view.md#laying-out-views---regions).
### MN0003: transfer ownership explicitly
A live View has one owner. Detaching transfers it without destroying it.
```javascript
import { Region, View } from 'marionette';
const first = new Region({ el: document.createElement('main') });
const second = new Region({ el: document.createElement('main') });
const child = new View({ template: () => 'Shared screen' });
first.show(child);
export function fail() { second.show(child); }
export function fix() {
second.show(first.detachView());
return second.currentView === child;
}
export function cleanup() { first.destroy(); second.destroy(); }
```
`fail()` throws MN0003. `fix()` returns `true`: the same child now belongs to the
second Region. Use a new View when both places must display content simultaneously.
See [detaching a View](https://github.com/marionettejs/marionette/blob/9404b1935b855e05c982f697d8471764a140e8f6/docs/marionette.region.md#detaching-existing-views).
### MN0023: bind UI after rendering
A selector declaration is available before render; its matching elements are not.
```javascript
import { View } from 'marionette';
const view = new View({
template: () => '',
ui: { save: 'button' }
});
export function fail() { view.getUI('save'); }
export function fix() {
view.render();
return view.getUI('save')[0].textContent;
}
export function cleanup() { view.destroy(); }
```
`fail()` throws MN0023. `fix()` returns `Save`. Access bound UI in `onRender` or
after rendering; after explicitly unbinding, bind it again before lookup.
See [UI bindings](https://github.com/marionettejs/marionette/blob/9404b1935b855e05c982f697d8471764a140e8f6/docs/dom.interactions.md#organizing-a-view-with-ui).
### MN0007: replace a destroyed instance
Destruction ends a View's lifetime. Create another instance for a new screen.
```javascript
import { Region, View } from 'marionette';
const region = new Region({ el: document.createElement('main') });
const old = new View({ template: () => 'Old' });
old.destroy();
export function fail() { region.show(old); }
export function fix() {
region.show(new View({ template: () => 'New' }));
return region.currentView.el.textContent;
}
export function cleanup() { region.destroy(); }
```
`fail()` throws MN0007. `fix()` returns `New`. A stopped Application may restart;
a destroyed View may not. See [View destruction](https://github.com/marionettejs/marionette/blob/9404b1935b855e05c982f697d8471764a140e8f6/docs/view.lifecycle.md).
## Report an unresolved problem
Include the exact package/source identity, browser and bundler, selected adapters,
the smallest public-API reproduction, and expected versus observed behavior.
[Open an issue](https://github.com/marionettejs/marionette/issues/new/choose).
Do not include private application data.
Synchronous construction, registration, rendering, and cleanup failures abort the
operation. Fix the source of the failure; do not rely on automatic rollback or
catch an exception and continue a partially completed operation. The ownership
checks illustrated here and Application's documented asynchronous cancellation
are existing contracts. See the [synchronous failure boundary](https://github.com/marionettejs/marionette/blob/9404b1935b855e05c982f697d8471764a140e8f6/docs/view.lifecycle.md#synchronous-failures).
[Canonical source](/development/source/docs/troubleshooting.md) ยท [Source identity](/development/manifest.json)