Troubleshooting

When something goes wrong, Resonon usually tells you what and where. This guide is organized by symptom: find the heading that matches what you see, then work through the numbered fixes. Quoted blocks are the exact messages Resonon prints.

MIDI

Octaves look an octave off

Resonon uses scientific pitch notation: C4 is MIDI note 60. Ableton Live (and a few other DAWs) label that same note C3. The MIDI numbers are identical — only the octave label differs, so nothing is actually wrong.

Resonon	MIDI note	Ableton label
C4	60	C3
A4	69	A3
C5	72	C4

No notes reach the DAW

MIDI port “default” is not connected — 3 events dropped. Use midi_connect(“<port name>”) to connect.

Resonon dropped the events because no MIDI port was connected. This warning is expected when you run with --no-midi (see Headless mode); during live coding it means you never connected a port.

1. Connect a port by name (partial names match): midi_connect("IAC");
2. Or pass one at startup: resonon -m "IAC" script.non
3. Check the connection at any time — midi_connected() returns the port name (or false):

midi_connect("IAC Driver");
PRINT(midi_connected());

On the DAW side, also confirm the track is record-armed / input-monitored, its MIDI From shows your virtual port, and an instrument is loaded.

Port not found

1. List what’s available: resonon --list-ports
2. Make sure a virtual MIDI port exists (IAC Driver on macOS, loopMIDI on Windows, ALSA virtual ports on Linux)
3. Port matching is by substring, so "IAC" matches "IAC Driver Bus 1"

Stuck or hanging notes

A note hangs when its note-on was sent but the matching note-off never arrived (often after re-evaluating mid-note).

1. Press PLAY again — on resume the engine chokes lingering voices and sends an all-notes-off, which clears stuck notes
2. STOP; halts playback and resets to the start of the cycle; PAUSE; suspends in place
3. For a note stuck inside an external DAW, trigger the DAW’s own panic / all-notes-off
4. Quitting Resonon disconnects every MIDI port cleanly

Headless mode

Run a script without connecting to MIDI:

resonon --no-midi script.non

In this mode Resonon evaluates everything and renders audio, but MIDI output is disconnected — sending events to a MidiTrack logs the “port is not connected” warning above and drops them. It is the right mode for syntax-checking, testing pattern logic, and CI, where no DAW is listening. This is exactly how the documentation snippets are verified.

Audio engine

No audio output

No audio output device found

1. Check that your system has an output device selected and enabled
2. On macOS, open Audio MIDI Setup and confirm an output device is active
3. On Linux, confirm PulseAudio (pactl info) or PipeWire (wpctl status) is running
4. Close other apps that may hold the device exclusively

Stream errors

Failed to build stream: … / Failed to start stream: …

1. Close other audio applications (DAWs, browser tabs playing audio)
2. Confirm the device supports the requested sample rate
3. Try a different output device, or set one explicitly in configuration under [audio]
4. Restart Resonon after changing audio hardware

Input and output sample rates differ

Input sample rate (44100) must match output sample rate (48000)

When you use audio input, the input and output devices must run at the same sample rate.

1. Open your system audio settings
2. Set both devices to the same rate (typically 44100 or 48000)
3. On macOS, verify both in Audio MIDI Setup

Crackles or high latency

1. Lower your system audio buffer size (256 or 512 samples is a good starting point)
2. Close other audio applications
3. Some interfaces expose buffer size in their own control panel or in Audio MIDI Setup

Samples and kits

Sample file not found

Sample file ‘kick.wav’ not found. Searched: [cwd, …]

1. Relative paths resolve from the current working directory — check where you launched Resonon
2. Confirm the file exists at that path
3. For kit directories, set kit_paths in your configuration
4. Only WAV files are supported — convert other formats first

Failed to load a sample

Failed to load sample: …

The file was found but could not be decoded as audio.

1. Re-export as standard PCM WAV (16- or 24-bit integer)
2. Compressed formats (MP3, OGG, FLAC) and 32-bit float WAV are not supported
3. Verify the file is not corrupt by opening it in another application

Kit fails to load

Failed to load kit ‘mykit’ into sampler plugin

1. Check kit.toml for a syntax slip — a missing comma or bracket fails the parse
2. Confirm every sample path in kit.toml points to an existing WAV file
3. Without a kit.toml, WAV files in the directory are assigned sequential notes from C2

Sample name not in the kit

Sample ‘clap’ not found in kit ‘CR-78’. Available samples: [“bd”, “rs”, “sd”, …]

The kit loaded, but you referenced a name it does not define. The message lists every name the kit does provide — pick one of those, or add the sample to kit.toml.

Melodic samplers play at the wrong pitch

A melodic sampler needs a root note to transpose samples correctly.

1. Pass it explicitly: sampler("piano.wav", root: 60)
2. Or set it per sample in kit.toml
3. Without a root note, the sampler cannot pitch the sample correctly

See Samplers for kit layout and root notes in depth.

Plugins

Plugin not found

1. Scan first — plugin_scan() walks the CLAP and VST3 directories and builds the cache, returning the list of what it found
2. Confirm your .clap file sits in a standard search path:
   • macOS: /Library/Audio/Plug-Ins/CLAP, ~/Library/Audio/Plug-Ins/CLAP, ~/.clap
   • Linux: /usr/lib/clap, /usr/local/lib/clap, ~/.clap
   • Windows: C:\Program Files\Common Files\CLAP
3. Bundled plugins (such as the built-in sampler) are always available without scanning

Plugin listed but won’t load

1. Confirm the plugin’s architecture matches Resonon’s (e.g. arm64 vs x86_64 on macOS)
2. Re-download or reinstall in case the .clap file is corrupt
3. Some plugins depend on system libraries — check the vendor’s documentation

No plugin GUI

plugin does not support the CLAP GUI extension

Not every CLAP plugin ships a GUI, and bundled plugins have none.

1. List parameters with .params()
2. Set them programmatically with .param_set(name, value)
3. If a third-party plugin should have a GUI, make sure you have its latest version

No plugin cache

No plugin cache found. Run resonon plugin scan first.

1. From a script, call plugin_scan(); from the shell, run resonon plugin scan
2. Inspect the returned list to see what was found
3. You only need to rescan after installing or removing plugins

See Plugins for the full scanning and parameter workflow.

Language errors

Undefined function or method

Undefined function ‘reverb’

1. Check spelling — names are case-sensitive
2. Audio effect and instrument constructors are part of the prelude and available globally (Delay, Reverb, Lowpass, …) — no import needed
3. Anything from a user module needs a use statement first (see Modules)

Type errors

Expected Number, got String

1. Check argument types — passing a string where a number is expected is the usual cause
2. MIDI note values are integers (60, not "60")
3. See Values & Variables for the type rules

Wrong number of arguments

‘pan’ expects 1 arguments, got 2

You passed too few or too many arguments. Check the call against the function’s signature in Functions — a common cause is a missing required argument.

Index out of bounds

Index out of bounds: index 5 is out of range for length 3

Arrays are zero-indexed: a length-3 array has valid indices 0, 1, 2.

1. Verify the length with .length()
2. For cyclic access, wrap with modulo: arr[i % arr.length()]

let arr = #[10, 20, 30];
for i in range(6) {
    PRINT(arr[i % arr.length()]);   // cycles 10, 20, 30, 10, 20, 30
}

See Collections for indexing rules.

Signals and modulation

Zipper noise on a modulated parameter

Stepped or abruptly changing signals can click (“zipper noise”) when they drive an audio parameter. Run the signal through .smooth(ms) — a one-pole lowpass that rounds the jumps:

delay.param("Time") << signal(#[0.1, 0.2, 0.35, 0.15]).smooth(10);  // 5–20 ms is typical

More on signals and smoothing in Signals & Automation.

Patterns and timing

Events bunch up at the cycle edge after a big nudge

.nudge() (and .swing(), which builds on it) clamps each event to the current cycle: an event pushed past the cycle boundary lands on the edge rather than crossing into the next cycle. With large offsets, several events can pile up at the edge.

1. Keep offsets well within the cycle range (e.g. ±0.1)
2. Reduce the nudge magnitude until the timing reads the way you intend

Swing only shifts every other event

That is swing working as designed: even-indexed events stay on the grid, odd-indexed events shift forward. For per-event control, use .nudge() with your own offset pattern instead.

See Microtiming for nudge, swing, and humanize.

Server and VSCode

VSCode can’t connect

1. Confirm the server is running: resonon server
2. Check the port is free: lsof -i :5555 (5555 is the default)
3. Make sure your firewall allows the connection
4. Bind an explicit host if needed: resonon server --server-host 127.0.0.1

No output in VSCode

1. Use PRINT or PUT to emit output — bare expressions print nothing
2. Open the Output panel and select the RESONON channel
3. Confirm the status bar shows a live connection

Server won’t start

1. The port may already be in use — pick another: resonon server --server-port 5556
2. Binding to 0.0.0.0 (the default) can require permission on locked-down systems — try --server-host 127.0.0.1

See VSCode Extension and Server & Collaboration for setup details.

See also

• MIDI Out — connecting ports and sending notes
• Clock Sync — virtual MIDI and DAW transport
• Samplers — sample loading, kits, and root notes
• Plugins — CLAP/VST3 scanning, loading, parameters
• Signals & Automation — signal types and smoothing
• Microtiming — nudge, swing, humanize
• Configuration — audio devices, MIDI ports, kit paths

Next steps

• CLI Reference — every command and flag in one place
• Live Coding vs Offline Rendering — when to use the server versus resonon run