troubleshooting.md

(help-troubleshooting)=

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

1. Open Advanced > Diagnostics and click Run preflight check before a first hardware run or after changing device settings.
2. Confirm the correct backend:
   • loopback for testing without hardware;
   • hardware for real processor measurement.
3. If using hardware, confirm the processor is connected and powered on.
4. Confirm the Reference DI path points to an existing WAV.
5. Confirm playback and recording channels match your processor routing.
6. Confirm MIDI output and MIDI channel are correct.
7. Confirm selected presets have snapshots that are not all ignored.
8. 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

1. Open the Log tab and look for the warning.
2. Check whether the snapshot recorded silence.
3. Check audio routing.
4. Use the recorded-output playback button if available.
5. Rerun the preset after fixing routing or timing.
6. 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.

(help-hardware-not-found)=

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

1. Check that the processor is powered on.
2. Check the USB cable.
3. Check that the processor appears as an audio device.
4. Check that the processor appears as a MIDI output.
5. In Advanced > Device, make the Audio device and MIDI output names more specific.
6. 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

1. On the Pod Go, open Global Settings > MIDI/Tempo.
2. Enable MIDI Program Change receive.
3. Confirm the Pod Go MIDI base channel matches MatchPatch's MIDI channel, or set the Pod Go to receive on all channels.
4. If MatchPatch is sending to a loopMIDI port for capture, configure MIDI-OX to route that input to the real POD Go MIDI output.
5. 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

1. Open Advanced > Files.
2. Click Browse beside Reference DI.
3. Choose an existing WAV file.
4. 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

1. Open Advanced > Files.
2. If the Config field points to a file, confirm it is the file you meant to use.
3. 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

1. Use a reference DI recorded at the same sample rate as the processor audio setup.
2. Or change the Sample rate in Advanced > Device to match the WAV and hardware.
3. 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

1. Open Advanced > Device.
2. Make the Audio device field more specific.
3. If multiple similar devices are visible, use the exact name shown by your system.
4. 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

1. Open Advanced > Device.
2. Check Recording channels.
3. Check Playback channels.
4. Try the usual Line 6 hardware idea:
   • Recording channels: 1,2;
   • Playback channels: 3,4.
5. 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

1. Check that presets are selected.
2. Check that the ignored snapshot rule is not skipping everything.
3. Check the snapshot count.
4. Select a known non-empty preset.
5. 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

1. Click the Preset cell.
2. Enter one slot, such as 12A.
3. Use a slot from 01A through 32D.
4. 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

1. Open the current .hls or .pgs setlist.
2. Click Select changed.
3. 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

1. Use shorter names.
2. Avoid unusual symbols.
3. Use letters, numbers, spaces, and common punctuation.
4. 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

1. Check routing.
2. Check the Reference DI.
3. Use recorded-output playback.
4. Use Default timing instead of Fast.
5. Increase snapshot wait for presets with long trails.
6. 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

1. Check routing first.
2. Check that the preset produces sound.
3. Check that the output block is active.
4. Rerun the preset.
5. 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

1. Open the preset in the matching editor or on the processor.
2. Remove unused snapshot assignments from blocks or parameters.
3. Save the preset or setlist.
4. 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

1. Use the Default timing preset.
2. Increase snapshot wait or measurement wait.
3. 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

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

(help-csv-errors)=

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

1. Open the same setlist the CSV came from.
2. Make sure the snapshot count is the same.
3. Make sure preset IDs still exist in the table.
4. Check that gain values are numbers.
5. 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

1. Make one row per preset.
2. Put the preset slot first, such as 01A.
3. Add one value column per measured snapshot.
4. Leave cells empty when no custom adjustment is needed.
5. 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.