Skip to content

Validation & errors

Validate a mapping bundle with map-check, read its exit codes and errors, and contribute a mapping.

map-check is the controller crate’s static validator. It loads and checks a mapping bundle with no hardware. A bad device.toml, map.toml, or script.rhai shows up before you launch the app. The same checks run in CI over every shipped bundle.

Validate a bundle

Run map-check from crates/:

cargo run -p controller --bin map-check -- --all ../mappings
  1. Choose what to check. --all checks every bundle; a directory or an id checks one.
  2. Fix every failure. The failure lines go to stderr and the process exits non-zero.
  3. Rerun until the bundle prints ok, then keep it green.

A failure looks like this:

ERR ddj-400: inputs.deck_1.volume: no matching endpoint in device.toml
Invocation Checks
--all [root] Every immediate subdirectory of root. The root defaults to ../mappings when omitted.
<bundle-dir> A single directory.
<id> Resolved as ../mappings/<id>, falling back to mappings/<id>.
# One bundle directory
cargo run -p controller --bin map-check -- ../mappings/ddj-400

# A bundle id, resolved under ../mappings/ (then mappings/)
cargo run -p controller --bin map-check -- ddj-400

On success each bundle prints one ok line, followed by a count:

ok  ddj-400
1 bundle(s) ok

A single-directory run prints the path instead of the id:

ok  ../mappings/ddj-400
Exit code Meaning
0 Everything passes.
1 Any bundle fails.
2 Usage error (no arguments prints the usage text).

With --all, a failure prints ERR <id>: <reason> for each bad bundle, and nothing is reported as ok.

Contribute a mapping

Start from the Controller mapping issue template (label enhancement, title controller: …). Fill in:

  • Device: Product; Vendor / model; MIDI name / USB VID:PID (if known).
  • References: the official MIDI chart, manufacturer page, and any Mixxx or other mapping you used.
  • What’s wanted: transport, mixer, jog, pads, LEDs, relative CC, and which parts are must-haves versus nice-to-haves.

Then add the bundle:

mappings/<id>/
  device.toml     # required — identity + endpoints
  map.toml        # required — inputs, outputs, lifecycle
  script.rhai     # optional — only if hooks or script bindings are used

Keep map-check green. CI runs check_all_mappings over mappings/, so any bundle that fails validation fails the build. The shipped mappings/ddj-400/ bundle is the reference to study. It shows note and cc14 endpoints, relative jog CCs, per-bank pad aliases, LED outputs, and a script.rhai with lifecycle hooks. The older example-generic template has been retired in favor of these docs.

What map-check validates

The checks span the whole bundle.

Bundle layout

  • Both device.toml and map.toml must exist. A missing file is reported as missing required file ... with its full path.
  • Both files must parse as TOML and declare schema_version = 1. Any other version fails with unsupported schema_version <n> (expected 1).

device.toml

  • Section names must be one of master, sampler, custom, or deck_N.
  • A deck_N index must be in the v1 range 1..=4.
  • Every alias must be snake_case.
  • Every endpoint must have a valid shape (see the endpoint rules below).
  • Two input-eligible endpoints may not claim the same MIDI identity. Overlap is rejected as an input MIDI clash.

map.toml inputs

  • Each alias must be in the closed input catalog for its section.
  • Each alias must have a matching endpoint in device.toml.
  • Each binding must name exactly one of action or script.
  • A named action must be a known action id.
  • A named modifier must exist in device.toml (and be written as custom.*).
  • A relative CC endpoint must be paired with a relative action, and vice versa. Relative control is only for jog_turn and navigate.
  • A script binding requires script.rhai to be present.

map.toml outputs

  • A watch key must be in the closed catalog for its section (except under custom).
  • Each on / off target must either resolve to an alias in device.toml or be a valid inline endpoint.

Lifecycle and script.rhai

  • Declaring any [lifecycle] hook requires a script.rhai in the bundle.
  • Every function named by a lifecycle hook (on_init, on_shutdown, idle_heartbeat) must be defined in script.rhai.
  • Every function named by an input binding’s script must be defined in script.rhai.
  • script.rhai must compile; a syntax error is reported as script compile error: ....

Endpoint shape rules

The rules apply to device endpoints, inline output targets, and alias/inline output resolution:

Rule Error when violated
channel is 1..=16 channel must be 1..=16, got <n>
type = "note" carries note note message requires note
type = "cc" carries a 7-bit cc cc message requires cc / type=cc expects cc = <u8>; use type=cc14 for msb/lsb
type = "cc14" carries { msb, lsb } and msb != lsb cc14 requires cc = { msb = …, lsb = … } / cc14 msb and lsb must differ
relative is set only on type = "cc" relative is only valid on type=cc (7-bit)

Common errors

Messages below use the real shapes, with ... standing in for a path or bundle id.

Message Cause Fix
missing required file .../device.toml bundle has no device.toml add the file
missing required file .../map.toml bundle has no map.toml add the file
failed to parse ...: ... invalid TOML or a wrong field type fix the TOML around the reported line
unsupported schema_version <n> (expected 1) missing or wrong schema_version set schema_version = 1 in both files
unknown device section 'deck_5' section isn’t master / sampler / custom / deck_N rename it to a valid section
deck index 5 out of v1 range 1..=4 a deck_N section with N > 4 use deck_1…deck_4
deck_1.volumeTrim: alias must be snake_case alias has capitals or dashes rename to volume_trim
note message requires note type = "note" without note add note = 0x..
cc message requires cc type = "cc" without cc add cc = 0x..
cc14 requires cc = { msb = …, lsb = … } type = "cc14" without cc add the msb/lsb pair
type=cc expects cc = <u8>; use type=cc14 for msb/lsb msb/lsb used on type = "cc" switch to type = "cc14"
cc14 msb and lsb must differ msb and lsb are equal pick two different CC numbers
relative is only valid on type=cc (7-bit) relative set on note or cc14 use type = "cc" for relative controls
channel must be 1..=16, got 0 channel out of range use 1..=16
input MIDI clash: 'deck_1.play_pause' and 'deck_2.play_pause' share the same type/channel/note|cc two inputs claim the same MIDI identity give them different channels / notes / CCs
inputs.deck_1.foo: not in closed catalog for 'deck_1' alias typo or unsupported name use a catalog alias for the section
inputs.deck_1.volume: no matching endpoint in device.toml input alias absent from that device section add the endpoint (or remove the input)
inputs.deck_1.volume[0]: binding needs exactly one of 'action' or 'script' binding has both or neither keep exactly one
inputs.deck_1.play_pause[0]: unknown action 'Deck(_)::foo' action leaf typo or unknown action use a known action id
inputs.deck_1.volume[0]: modifier must be 'custom.*', got 'shift' modifier isn’t namespaced custom. write custom.shift
inputs.deck_1.volume[0]: modifier 'custom.shift' missing from device.toml custom.shift endpoint not defined add it under [custom] in device.toml
inputs.deck_1.volume[0]: relative CC endpoint mismatch for action 'Deck(_)::set_volume' (set relative = … on device only for jog_turn/navigate) relative endpoint/action mismatch align them: no relative for absolute faders
script 'my_hook' referenced but script.rhai is missing a binding names a script but no file ships add script.rhai
[lifecycle] requires script.rhai in the mapping bundle [lifecycle] declared without script.rhai add the file or drop the hooks
lifecycle.on_init: script function 'x' not found in script.rhai hook names a missing function define it in script.rhai
inputs.deck_1.play_pause[0]: script function 'x' not found in script.rhai binding names a missing function define it in script.rhai
script compile error: ... Rhai syntax error in script.rhai fix the script
unknown inputs section 'deck_5' [inputs.…] uses an invalid section use a valid section name
unknown outputs section 'deck_5' [outputs.…] uses an invalid section use a valid section name
outputs.deck_1.foo: watch key not in closed catalog output watch key typo use a catalog alias
outputs.deck_1.play_pause.on: alias 'foo_led' missing from device.toml output target alias not defined add the LED/endpoint
outputs.deck_1.x.blink: 'blink' requires 'signal' (otherwise the binding is never resolved) binding declares blink without signal add signal = "…"; see outputs
outputs.deck_1.x: unknown signal 'foo' for 'deck_1' signal outside the section’s closed catalog use a catalog signal for that section
no mapping bundle directories found in '...' --all pointed at an empty or wrong root pass the real mappings/ root
failed to read '...' I/O error (missing root, permissions) fix the path or permissions
  • device.toml: identity, sections, and endpoint shape.
  • inputs: [inputs] binding forms, fields, modifiers, soft takeover.
  • outputs: [outputs] signals, LED modes (on/off/blink), caching and refresh.
  • lifecycle: [lifecycle] hooks and when the session calls them.
  • Actions: the action ids you can bind.