Troubleshooting

Troubleshooting

Organised by symptom. Find the entry that matches what you are seeing.

Setup

A tool shows [NOT FOUND] in Settings ▸ Tool paths

RemuxForge could not find the executable on PATH and no valid explicit path is set.

Verify from a terminal:

mkvmerge --version
mkvextract --version
mkvpropedit --version
ffmpeg -version
ffprobe -version
mediainfo --Version

Any that fail are not installed, or not on the PATH the RemuxForge process sees. Which is not always the one your shell has, especially when RemuxForge runs as a service. Set the full path explicitly in Settings ▸ Tool paths.

For ffmpeg/ffprobe on Windows and Linux, the dialog has a [ Download ] button that fetches FFmpeg 9 stable and configures both paths. The same download also runs automatically the first time a job needs ffmpeg. On macOS automatic download is disabled: install the FFmpeg 9 full build with brew install ffmpeg-full or set the path manually.

MediaInfo shows [CLI NOT FOUND]

You installed the MediaInfo GUI, which does not provide the mediainfo executable. Install the CLI package:

sudo apt install mediainfo          # Debian/Ubuntu
brew install media-info             # macOS
winget install MediaArea.MediaInfo.CLI

Metadata mode cannot scan at all without it.

A tool shows [ERROR]

The path exists but the executable failed to run, wrong architecture, missing shared libraries, or no execute permission. Run it manually from a terminal and read the actual error.

The WebUI will not open

1. Is the process still running? It logs its listening address at startup.
2. Is the port taken? lsof -i :5000 on Linux/macOS, netstat -ano | findstr :5000 on Windows. Change it with --port 5050 or REMUXFORGE_PORT=5050.
3. On macOS, a downloaded binary is quarantined and will not start: xattr -d com.apple.quarantine RemuxForge.Web.
4. Remote access: the server binds 0.0.0.0, so a firewall is the usual cause. There is no authentication; do not open the port to the internet.

The application will not start, or settings are not saved

It cannot write its data directory. Check ownership and free space on .remux-forge. Under Docker that is the /data mount:

sudo chown -R 1000:1000 /path/to/config

Desktop

The desktop window shows RemuxForge could not start

The Tauri shell could not start its local WebUI sidecar, or the sidecar exited unexpectedly. Read the error shown below the message, correct the reported problem, then press Retry. Typical causes are a damaged/incomplete application bundle or a non-writable application-data directory.

Desktop data is stored outside the installed application:

• Windows: %LOCALAPPDATA%\RemuxForge\.remux-forge
• macOS: ~/Library/Application Support/RemuxForge/.remux-forge

Moving or replacing the installed application therefore does not remove settings and presets.

A second desktop launch appears to do nothing

Only one instance is allowed. A second launch focuses and restores the existing RemuxForge window instead of starting another local server.

macOS refuses to open a locally built .app

Current development and release bundles are not signed or notarized. For a trusted download, use Finder's Open context-menu action or choose Open Anyway under macOS Privacy & Security; do not disable Gatekeeper globally.

Docker

Scan finds nothing although the path exists

Paths in the WebUI are container paths. With -v /mnt/tank/media:/media, type /media/Series, not /mnt/tank/media/Series.

Use the [ .. ] browse button instead of typing. It can only show what the container can actually see, which makes the mistake obvious. See Docker.

Permission denied when writing output

The container user cannot write the target. Set user: "1000:1000" to your own UID/GID, make sure that user owns the mounted folders, and mount :rw rather than :ro. Overwrite-in-place needs write access to the media mount, not just the output one.

Hardware acceleration does nothing

There are two independent GPU paths. Hardware Acceleration affects FFmpeg decoding during analysis; Analysis ▸ Vision backend ▸ Vulkan affects visual compute. In Docker the device must first be passed through with --gpus all or --device /dev/dri:/dev/dri. Encoding always uses the software encoders, and analysis never enables either path on its own.

Vulkan cannot be selected

The settings dialog initializes the Vulkan runtime, device and SIFT compute pipeline before accepting the selection. A failure means the process cannot see a Vulkan 1.2 loader and a compatible compute device with timeline semaphores.

• Windows: update or install the GPU vendor driver.
• Linux: install libvulkan1 and the correct vendor ICD; Intel/AMD commonly use mesa-vulkan-drivers.
• macOS: install the Vulkan SDK and MoltenVK runtime.
• Docker: use a Linux host, expose the GPU, and include graphics in NVIDIA_DRIVER_CAPABILITIES on NVIDIA.

The error shown in the dialog is the probe result. CPU remains selected after a failure. See Installation and Docker.

Remux: scanning and matching

Scan finds no files

• Check Extensions. The default is mkv; a folder of .mp4 returns nothing.
• Check Recursive if files are in per-season subfolders.
• Confirm the path, under Docker see above.

In single-file mode Source and Language must both be files

One side points at a file and the other at a folder. Either select a file on both sides, or a folder on both. For a filter-only job with no import, leave Language empty.

File extension is not allowed by the configuration

The selected file's extension is not listed in Extensions. Add it, or select a file that matches.

Episodes are Skipped with No match or No episode ID

The match pattern is not producing pairable IDs.

• No episode ID. The pattern did not match the source filename at all.
• No match. An ID was derived but no language file produced the same ID.

Read the log after F5: it reports how many source files were found and how many language files were indexed. A language count of 0 means the pattern never matched the donor side.

The most common cause is zero-padding: S12E08 gives 12_08, S12E8 gives 12_8, and those are different strings. Either use a pattern that normalises it, or fix one side with Bulk Rename.

Regex recipes: Codec and Language Reference.

Episodes are Skipped with No matching tracks

The pair matched, but the Language file has no track in your target language after filtering.

• Check the language code. ger and deu are both valid and both different strings. Open Language MediaInfo from the context menu and read what the file actually says.
• Check your Audio codec filter. Bare DTS matches only the DTS core, not DTS-HD MA.
• With Subtitles only or Audio only set, the other kind is ignored.

The result is missing an expected language

Analyze, select the row, and read FINAL RESULT in the detail panel. If the language is absent there, the cause is in Target language, the codec filter, or the Keep filters, not in the sync settings.

Remember empty Keep fields keep everything, not nothing.

Remux: synchronization

Frame-sync fails or reports low confidence

The detail panel gives a Reason when it fails outright.

• Geometry bootstrap failed: automatic border detection or the first-three-minute SIFT consensus could not establish a common picture. Use Crop src / Crop lang (L:R:T:B) only when non-black overscan or unstable edges defeat the automatic crop. This never crops the output.
• Too few measurable frames: dark, static or repeated checkpoint windows may not provide enough dHash support. Use Deep analysis, or set the delay by hand with the per-episode Delay dialog once it is known.
• The edits differ. Frame-sync produces a single offset. If the required delay changes mid-file, no setting will correct it: use Deep analysis.

Speed correction uses the wrong direction

Select the direction from the file that owns the final timeline (Source) to the imported donor (Lang). For example, choose Source 23.976 - Lang 25 when the final video is 23.976 fps and the imported Language release is a 25 fps transfer.

The CLI accepts an explicit --stretch-factor; the UI intentionally limits the choice to the six conversions between 23.976, 25 and 29.97 fps.

Deep analysis needs an audio format

Deep analysis rewrites the imported Language-audio timeline for the whole batch, even when a particular episode resolves to a constant delay and zero operations. Set Audio format (FLAC keeps it lossless) and Audio scope to Lang or All. See Remux Audio and Video.

Audio is still out of sync after merging

1. Did you analyze before processing? Without it, no sync method has run.
2. Read SYNCHRONIZATION in the detail panel. It tells you what was applied and with what confidence.
3. Wrong at a constant offset: nudge it with the per-episode Delay dialog (right-click the row). It adds to the automatic result.
4. Fine at the start, drifting later: that is a speed difference, not an offset. See speed correction above.
5. Right in places, wrong in others: the edits differ. Use Deep analysis.

Subtitles are misplaced or off screen after importing

The donor's subtitle coordinate space does not match the source video. Enable Rewrite subtitle canvas, and either Frame-sync or Deep analysis, since the rewrite consumes the geometry visual analysis produces. Without one of them it is silently ignored with a warning.

Read the log even when it appears to work. Unsafe cases fall back to the untransformed track and only report it there. ASS with rotation or shear tags under non-uniform scaling is skipped, because a coordinate rewrite cannot preserve the intended transform.

Imported audio has silence at the start or end

The dub does not cover the whole timeline. Enable Audio source fill with a threshold, a source language and the Start / End / Insert silence modes you need. The missing region is taken from a source audio track instead of being padded with silence. It requires an audio format and a scope of Lang or All. See Remux Synchronization.

Split

Pattern sum mismatch

Your chapter pattern's total does not equal the file's chapter count. Tick Dry-run, press F5 then F10, and read Found N chapters in the log. The count is only reported once F10 runs, since F5 in Split mode enumerates files without opening them. In folder batch mode every file must have the same chapter count for one pattern to work.

The cut is not at the requested position

Snap moved it to a keyframe. Set Snap = off for frame-perfect cutting, at the cost of re-encoding the head GOP of each segment, which is the slow path.

Conversely, if a split is taking far longer than expected, Snap is probably off and you may not need that precision.

Frame count mismatch

Source raw and the input file disagree on frame count, which means the frame indices do not correspond and every boundary would be wrong. Source raw must be the same content, same frame count, differing only in encoding.

Segment would overwrite input

A template would produce the input file's own name. The job aborts rather than destroying your source. Change the template or use a different output folder.

Existing segments are skipped

Force is off, so outputs that already exist are left alone, which makes an interrupted batch resumable. Enable it to overwrite.

chapters-each requires chapters

The file has no chapters. Use ranges or split points instead.

Unsupported video codec

Split mode handles HEVC and AVC only.

Metadata

Every row shows Changes = 0

Your rules matched nothing. Select a file, open Field detail, and compare its real values against your conditions.

• Language values are often two-letter (it) where you wrote three-letter (ita), or vice versa.
• Contains is case-sensitive against the actual stored string.
• A field may belong to a different scope than your rule's Apply to.
• The preset dropdown may still say No preset.

Everything says Stale analysis

The input path, output policy, recursion or preset changed after analysing, so the on-screen preview no longer matches the settings. Press F6 to re-analyze.

Execution says MkvMerge and processing is slow

Some rule requires a remux, most often a Remove track operation, sometimes an advanced field that cannot be written as a header edit. mkvpropedit patches headers in seconds; mkvmerge rewrites the whole file.

If that is not intended, locate the structural rule and remove it. If it is intended, allow for the additional time and disk space.

Manual edit rejects a change

Manual edit is a fast in-place path only. It rejects:

• Manual edit cannot remove tracks or require remux. Use a preset rule instead
• UI-managed tags do not include: X. That tag key is not available for this target
• Field X cannot be cleared. The field is not clearable

mkvpropedit failed / mkvmerge failed

Usually a read-only file, a lock held by another process, a full disk, or wrong ownership on the output. Under Docker, check the mount is :rw and the container user owns it.

Cannot read mkvmerge -J for metadata remux

The file is damaged or is not really an MKV. Verify it with mkvmerge -i file.mkv.

Bulk rename

The Rename button is disabled

Either the method stack is empty, or the preview reports conflicts or errors: both block the rename because either would lose a file.

A conflict means two files would end up with the same name in the same folder, usually because a method removed the part that distinguished them. Errors mean an invalid or empty name.

A method appears to do nothing

• Replace works on the whole filename including the extension; every other method works on the name only unless it has a Scope selector.
• An invalid regex disables that method. The status line reports Invalid regex.
• A By-position Remove whose range falls past the end of the name leaves the file unchanged.

Performance

Analysis is very slow

Deep analysis decodes and compares many video frames; it is the slowest thing in Remux mode.

• Enable Hardware Acceleration for FFmpeg GPU decode.
• Select Analysis ▸ Vision backend ▸ Vulkan to move Deep-analysis dHash and shared geometry work to a compatible GPU. The selection probes availability before it is saved.
• Under Docker, configure the required device passthrough and driver capabilities described in Docker.
• Frame-sync is much faster and applies when the edits are the same.
• Analyze a selection rather than the whole batch: select the rows that need it and press F6.

The remaining Advanced settings are matching thresholds. Lowering them makes the analysis faster and its results less reliable, which is difficult to detect afterwards, so they are not a general remedy for slow analysis. See Settings Reference.

Processing is very slow

• An encoding profile is set: re-encoding takes hours per episode at slow presets. Clear the profile if a re-encode is not required.
• Audio scope = All re-encodes the source tracks as well as the imported ones. Lang restricts the work to the imported tracks, if converting the source tracks is not the goal.
• Peak normalization roughly doubles audio work, because the peak must be measured on a full render first.
• In Split mode, Snap = off puts you on the slow path.

Review the active configuration and the selected row's detail panel to see which expensive steps are enabled.

Getting more information

1. The log panel is the first place to look. It carries warnings that never reach the file list.
2. REMUXFORGE_LOG_FILE=/path/to/log captures everything to disk, which is the form required for a bug report.
3. Diagnostics dumps (CLI only): --framesync-diagnostics and --deep-analysis-diagnostics write JSON to .remux-forge/framesync-diagnostics/ and .remux-forge/deepanalysis-diagnostics/.
4. MediaInfo from the context menu, source, language and result, is the ground truth about what a file actually contains.
5. Help ▸ Info gives the version to quote when reporting a problem.