Troubleshooting¶

Most MatchPatch problems come from one of four places:

the wrong backend;
missing or wrong hardware routing;
a missing reference DI;
a snapshot recording silence or unstable audio.

Start with the checklist below, then find the problem that matches what you see.

Start Here¶

Open Advanced > Diagnostics and click Run preflight check before a first hardware run or after changing device settings.
Confirm the correct backend:
- loopback for testing without hardware;
- hardware for real processor measurement.
If using hardware, confirm the processor is connected and powered on.
Confirm the Reference DI path points to an existing WAV.
Confirm playback and recording channels match your processor routing.
Confirm MIDI output and MIDI channel are correct.
Confirm selected presets have snapshots that are not all ignored.
If using a single preset file, confirm the temporary slot is filled in.

Preflight And Diagnostics¶

The Preflight check is the fastest way to diagnose setup problems before a full measurement. It validates the current file, selected presets, reference DI, effective settings, and hardware backend details when hardware mode is selected. For hardware mode, the native hardware check validates the selected audio device, audio channels, MIDI output, and timing settings from the Windows environment that will run the measurement.

Open Advanced > Diagnostics, then use:

Run preflight check to validate the current setup without writing adjusted files.
Copy diagnostic summary to copy resolved settings and recent context.
Export diagnostic bundle to save a support bundle for a bug report.

Diagnostic bundles are designed for troubleshooting, not for moving your tone files around. They include:

a human-readable summary;
structured diagnostic JSON;
effective MatchPatch settings;
recent GUI log lines;
recent progress events;
hardware/preflight check results;
retained CSV path and safe row summaries when available.

Diagnostic bundles intentionally exclude raw audio recordings, reference DI audio contents, preset or setlist contents, adjusted output files, and full retained CSV contents.

When sharing a bug report, attach the .zip created by Export diagnostic bundle and describe what you clicked immediately before the problem. If the issue is hardware-related, also mention whether the processor was visible to Windows as both an audio device and a MIDI output.

Red Highlighted Rows¶

What You See¶

One or more preset rows or snapshot cells are red after measurement.

Likely Cause¶

MatchPatch could not safely calculate a normal adjustment. It may have recorded silence, received unusable loudness data, or calculated an output level outside the processor range.

What To Try¶

Open the Log tab and look for the warning.
Check whether the snapshot recorded silence.
Check audio routing.
Use the recorded-output playback button if available.
Rerun the preset after fixing routing or timing.
If the tone really needs a special level, use manual editing or custom adjustments.

See Reading Results.

Warning: Do not keep raising output levels blindly after a failed measurement. First find out why the measurement failed.

No Suitable Device Connected¶

What You See¶

The GUI shows a hardware error, or measurement does not start in hardware mode.

Likely Cause¶

MatchPatch cannot see the processor audio device, MIDI output, or native hardware setup.

What To Try¶

Check that the processor is powered on.
Check the USB cable.
Check that the processor appears as an audio device.
Check that the processor appears as a MIDI output.
In Advanced > Device, make the Audio device and MIDI output names more specific.
If you only want to learn the app, switch Backend to loopback.

See Hardware Measurement.

Presets Do Not Switch On Pod Go¶

What You See¶

Snapshots change during measurement, but Pod Go presets stay on the same slot. In MIDI-OX, MatchPatch sends messages like C0 00, C0 01, or C0 02, followed by B0 45 00 through B0 45 03.

Likely Cause¶

Those messages are the expected Pod Go steering commands: Program Change selects the preset slot, and CC 69 selects snapshots. If snapshots move but presets do not, the Pod Go is receiving snapshot CC messages but ignoring Program Change, or the loopMIDI/MIDI-OX route is showing the messages without forwarding them to the Pod Go.

What To Try¶

On the Pod Go, open Global Settings > MIDI/Tempo.
Enable MIDI Program Change receive.
Confirm the Pod Go MIDI base channel matches MatchPatch’s MIDI channel, or set the Pod Go to receive on all channels.
If MatchPatch is sending to a loopMIDI port for capture, configure MIDI-OX to route that input to the real POD Go MIDI output.
If MatchPatch sends directly to POD Go, use MIDI-OX only for observation, not as the selected MatchPatch MIDI output.

Native Windows Environment Missing¶

What You See¶

Hardware mode fails when running from WSL or a Linux-side setup.

Likely Cause¶

The Windows audio/MIDI environment needed for hardware measurement is not ready.

What To Try¶

If you are not comfortable with command-line setup, ask the person who installed MatchPatch to prepare the Windows runtime.

If you only want to continue learning the GUI, switch to loopback mode.

See Test Without Hardware.

Reference DI File Missing¶

What You See¶

MatchPatch says the Reference DI WAV does not exist.

Likely Cause¶

The file path in Advanced > Files points to a missing or moved WAV.

What To Try¶

Open Advanced > Files.
Click Browse beside Reference DI.
Choose an existing WAV file.
Start again.

See Reference DI.

Config File Not Applied¶

What You See¶

MatchPatch starts with different backend, routing, Reference DI, or timing settings than you expected.

Likely Cause¶

The config file is not in the automatic search path, or another config file is selected in Advanced > Files.

What To Try¶

Open Advanced > Files.
If the Config field points to a file, confirm it is the file you meant to use.
If the Config field is empty, put your default config in the automatic location for your system.

Automatic config search path:

Windows installed app: %APPDATA%\MatchPatch\config.toml
Windows compatibility fallback: %USERPROFILE%\.config\matchpatch\config.toml
Linux/WSL/macOS with XDG_CONFIG_HOME: $XDG_CONFIG_HOME/matchpatch/config.toml
Linux/WSL/macOS fallback: ~/.config/matchpatch/config.toml

Reference DI Sample Rate Mismatch¶

What You See¶

Measurement starts but fails with a sample-rate message.

Likely Cause¶

The reference DI WAV sample rate does not match the configured audio sample rate.

What To Try¶

Use a reference DI recorded at the same sample rate as the processor audio setup.
Or change the Sample rate in Advanced > Device to match the WAV and hardware.
Try again.

Audio Device Not Found Or Ambiguous¶

What You See¶

MatchPatch cannot find the audio device, or says the audio device match is ambiguous.

Likely Cause¶

The Audio device field is empty, too broad, or does not match the device name.

What To Try¶

Open Advanced > Device.
Make the Audio device field more specific.
If multiple similar devices are visible, use the exact name shown by your system.
Reconnect the processor and restart the app if the device list changed.

Wrong Channel Mapping¶

What You See¶

Measurements are silent, wrong, or fail with bad LUFS.

Likely Cause¶

The reference DI is going to the wrong playback channels, or MatchPatch is recording the wrong return channels.

What To Try¶

Open Advanced > Device.
Check Recording channels.
Check Playback channels.
Try the usual Line 6 hardware idea:
- Recording channels: 1,2;
- Playback channels: 3,4.
Use recorded-output playback to confirm signal.

See Routing And Levels.

Warning: Wrong channels can record silence and create misleading loudness numbers.

No Measurable Presets¶

What You See¶

MatchPatch says there are no measurable presets or snapshots.

Likely Cause¶

All selected presets are empty, all selected snapshots are ignored, or the preset selection does not match the loaded file.

What To Try¶

Check that presets are selected.
Check that the ignored snapshot rule is not skipping everything.
Check the snapshot count.
Select a known non-empty preset.
Try again.

See Snapshots, Solos, And Ignored Snapshots.

Single-Preset Temporary Slot Missing¶

What You See¶

The GUI warns that a preset ID is required, or highlights the Preset cell.

Likely Cause¶

A single .hlx or .pgp preset needs one temporary device slot for measurement.

What To Try¶

Click the Preset cell.
Enter one slot, such as 12A.
Use a slot from 01A through 32D.
Start again.

See Normalize A Single Preset.

Output File Extension Mismatch¶

What You See¶

MatchPatch refuses to save the file.

Likely Cause¶

The saved file extension does not match the input.

What To Try¶

Save .hls setlists as .hls.
Save .hlx presets as .hlx.
Save .pgs setlists as .pgs.
Save .pgp presets as .pgp.
Use Save As and choose a matching filename.

See Save And Import Files.

Diff Input Must Use Same File Type¶

What You See¶

Select changed or diff selection fails.

Likely Cause¶

The previous file does not have the same extension as the current file.

What To Try¶

Open the current .hls or .pgs setlist.
Click Select changed.
Choose an older setlist of the same file type.

See Select Changed Presets.

Invalid Device Name¶

What You See¶

A table edit or CSV import complains about a device name.

Likely Cause¶

The preset or snapshot name contains a character the selected device workflow does not allow, or the name is too long.

What To Try¶

Use shorter names.
Avoid unusual symbols.
Use letters, numbers, spaces, and common punctuation.
For snapshot names, keep names very short.

See Manual Editing And CSV.

Bad LUFS Or Measurement Unavailable¶

What You See¶

The table shows a failed measurement, bad LUFS warning, or measurement unavailable warning.

Likely Cause¶

MatchPatch did not get usable loudness data.

Common reasons:

silence was recorded;
wrong USB channels;
the processor did not switch as expected;
the reference DI did not reach the processor;
the measured audio was too short for the analysis window;
timing was too fast for effect trails.

What To Try¶

Check routing.
Check the Reference DI.
Use recorded-output playback.
Use Default timing instead of Fast.
Increase snapshot wait for presets with long trails.
Rerun the affected preset.

See Measurement Timing.

Implausible Output Gain¶

What You See¶

MatchPatch warns that the resulting output level would be outside the processor range.

Likely Cause¶

The measurement was probably invalid, often because silence was recorded.

What To Try¶

Check routing first.
Check that the preset produces sound.
Check that the output block is active.
Rerun the preset.
If the preset is intentionally strange, use manual editing carefully.

Too Many Snapshot Assignments¶

What You See¶

MatchPatch says the selected device’s snapshot-assigned property limit would be exceeded.

Likely Cause¶

The preset already uses close to the selected device’s snapshot-assigned property limit. MatchPatch needs to assign the output block level to snapshots before it can balance snapshot loudness.

What To Try¶

Open the preset in the matching editor or on the processor.
Remove unused snapshot assignments from blocks or parameters.
Save the preset or setlist.
Run MatchPatch again.

Fast Timing Feels Unstable¶

What You See¶

Measurements vary between runs, or snapshots with delay/reverb produce strange results.

Likely Cause¶

Timing is too fast. One snapshot’s trails may still be ringing during the next snapshot’s measurement.

What To Try¶

Use the Default timing preset.
Increase snapshot wait or measurement wait.
Run Determine optimal parameters.

See Optimize Timing.

GUI Does Not Start On WSL¶

What You See¶

The GUI fails to open from a WSL setup.

Likely Cause¶

The graphical desktop support is not available or the required GUI packages are missing.

What To Try¶

If you are not technical, ask the person who installed MatchPatch to check WSLg or GUI package setup.
If you only need hardware measurement, consider running MatchPatch from the prepared Windows environment.

Preset Table CSV Import Errors¶

What You See¶

Loading a table CSV shows an error popup.

Likely Cause¶

The CSV does not match the current table.

What To Try¶

Open the same setlist the CSV came from.
Make sure the snapshot count is the same.
Make sure preset IDs still exist in the table.
Check that gain values are numbers.
Check that names are short and valid for the selected device.

See Manual Editing And CSV.

Custom Adjustment CSV Errors¶

What You See¶

The custom adjustment file is rejected.

Likely Cause¶

The file has the wrong number of columns, a duplicate preset ID, an empty preset ID, or a non-number adjustment.

What To Try¶

Make one row per preset.
Put the preset slot first, such as 01A.
Add one value column per measured snapshot.
Leave cells empty when no custom adjustment is needed.
Use small number values, such as 1.5 or -2.

See Custom Adjustments.

What To Listen For After Saving¶

After importing the adjusted file, play through the real setlist.

Listen for:

rhythm presets that still jump out;
leads that still disappear;
clean sounds that feel too quiet;
special effects that should be skipped;
snapshot changes that feel unnatural.

If only one snapshot needs a small change, use manual editing or a custom adjustment.

When To Rerun Measurement¶

Rerun measurement when:

routing was wrong;
the processor was not connected correctly;
a red row was caused by silence;
timing was too fast;
you changed the preset tone;
you changed the reference DI.