Troubleshooting

Fixes for the problems reported most often with freemkv and freemkv-library. Find your symptom below; if none match, capture a debug log (next) and open an issue.

Hit a specific Error: E<code> ... line? Look it up on the Error Codes page — every code is listed with its message, cause, and next steps.

First, make sure you’re on the latest version. Many reported problems are already fixed in a newer release — check the changelog and update before digging further. You can confirm your running version from the Checking versions section below.

Capturing a debug log

For any failure or hang, capture a debug log first; it’s the fastest path to a diagnosis and the one thing to attach to a bug report.

The CLI keeps the terminal clean by default and never prints raw diagnostics there. When something fails it prints a short block naming the cause and telling you exactly this: re-run with --log-level 3 to get a log. That writes a diagnostic log to ./log.txt (override the path with --log-file):

freemkv <source> <dest> --log-level 3              # writes ./log.txt
freemkv <source> <dest> --log-level 3 --log-file freemkv-debug.log

In freemkv-library, enable the Debug toggle in the web UI (or POST /api/debug), reproduce the problem, then collect the container logs.

In the desktop app (macOS, Windows, and Linux), the log panel shows the same detail as --log-level 3 as the rip runs — no flags to set. Use the copy button on the panel to grab it for a bug report.

For where files (config, keys, logs, staging, output) live, see your platform page: Windows, macOS, or Linux.

Sharing a profile (–share)

freemkv info <source> --share (short form -s) captures a shareable diagnostic profile — written as a zip and also printed as a base64 blob you can paste straight into a GitHub issue or an email. It’s the single command to run when we ask you to “send us the profile” for a drive-support or wrong-title bug report.

What it captures is context-aware by source:

• A physical drive with a disc loaded (freemkv info disc:///dev/sgN --share): captures both the drive profile and the disc structure.
• A physical drive with no media (freemkv info disc:// --share): the drive profile only — the historical behavior.
• An image or folder (freemkv info iso://Disc.iso --share, freemkv info dir://… --share): the disc structure only, since there is no drive.

The drive profile is the inquiry / feature / read-buffer captures for the drive — the data behind the community drive-compatibility database, so we can add or verify support for your drive.

The disc structure is metadata only. It contains the BDMV playlists (.mpls), clip info (.clpi), index.bdmv / MovieObject.bdmv, BD-J objects, and META XML, plus DVD VIDEO_TS IFOs — and a selection.json showing freemkv’s own title ranking. It carries no audio/video essence and no AACS keys, so it is safe to share. That’s exactly what lets us reproduce a wrong-title / disc-selection bug (like issue #45) without needing the whole disc — typically only a few hundred KB.

Sending it — paste the base64 blob into your issue or email, or attach / email the zip.

Redacting and submitting — add --mask to redact drive serials. On an official release build in an interactive terminal, freemkv then offers a [y/N] prompt (default no) to submit the profile as a GitHub issue for you. Nothing is sent unless you type y; otherwise freemkv prints the issue text for you to file yourself.

--share is its own command

--share does not combine with the info listing flags (for example --full); pairing them exits 1. See the CLI reference for the exact accepted flag set.

macOS: “app is damaged” / can’t open

Install through Homebrew, the supported macOS installation route. The releases are not notarized. Removing a downloaded executable’s quarantine attribute may allow it to launch, but does not establish that macOS will authorize drive access.

brew update
brew install --cask freemkv/tap/freemkv

For the CLI, use brew install freemkv/tap/freemkv-cli. If already installed, use brew upgrade with the same package name.

Firmware tools: list works but info reports E1006

list reads the macOS device registry; info must open the drive’s native interface. A successful listing does not establish permission to open it. E1006 with 0xe00002be can mask an authorization failure inside Apple’s plug-in.

For a browser-downloaded firmware tool, install the Homebrew package and run that installed command, rather than the old ./freemkv-flash-… file in Downloads:

brew update
brew install freemkv/tap/freemkv-flash
freemkv-flash --version
freemkv-flash info 1

Use brew upgrade freemkv/tap/freemkv-flash if already installed. If it still fails, attach the automatic diagnostic log named by the command. Homebrew installation has resolved this failure in a reported case, but the error code alone does not identify which macOS authorization check failed.

No drives detected in freemkv-library

The container is missing privileged: true. Without it the container starts normally but enumerates zero drives, and the UI shows “No drives detected” with no other error.

services:
  freemkv-library:
    # required for optical SCSI access
    privileged: true
    volumes:
      # required: exposes host devices to the container
      - /dev:/dev

Confirm both privileged: true and the /dev:/dev bind mount are present, then restart the container. See Deploy.

No drive found on the CLI

If freemkv info disc:// reports no drive:

• On Linux, prefer the SCSI generic device (/dev/sg*). A /dev/sr* path is also accepted and auto-resolved to its matching sg node via sysfs, so either works:

  freemkv info disc:///dev/sg4

• Confirm your user has permission to access the device node.

No decryption keys available

You tried to read an AACS-encrypted disc (Blu-ray or 4K UHD) and no key source had its key. The CLI says something like “This disc needs AACS decryption keys, but no key source provided them” or “No key source has a decryption key for this disc” (often with the disc’s id). DVDs are never affected.

Next steps — Blu-ray and 4K UHD need decryption keys you provide, from either of two key sources:

• A local key database (keydb.cfg): download or refresh it with freemkv update-keys --url <keydb-url>, or point --keydb PATH at one you already have.
• An online key service: configure it with --key-url URL.

Decryption Keys covers both options for the CLI and for freemkv-library.

Drive rejected the disc’s security credentials

If you have keys but the rip still fails at the drive handshake (the error says the drive rejected this disc’s security certificate or rejected the AACS host certificate), the drive refused to start the secure session needed to read the disc:

• Update your key database first (freemkv update-keys --url <keydb-url>). A stale or incomplete keydb is the most common cause.
• If the keys are current and it still fails, the disc may need a firmware-unlockable drive. Some drives can be unlocked to read protected discs and others cannot; on a drive that can’t be unlocked another way, this handshake is the only path and there’s nothing more to try on that drive. Use a drive that supports unlocking.
• Make sure nothing else is using the disc; a busy drive can refuse to start a secure session.

Re-run with --log-level 3 (writes ./log.txt) and attach the log if you open an issue.

Bad sectors on a disc

freemkv is built to recover damaged discs, but behavior depends on the mode:

• Single-pass (CLI direct disc → MKV, or freemkv-library max_retries = 0): no retries. For a per-title mux (MKV/M2TS/etc.) a read error fails the rip; for a whole-disc iso:// or null:// copy the image is kept and reported as damaged instead (CLI exit code 3 — see Exit codes).
• Multipass (CLI --multipass, or freemkv-library max_retries ≥ 1): the sweep records bad ranges and skips ahead; patch passes then re-read only those ranges from the disc. Use this mode for any disc you suspect is scratched. See How recovery works.

Tips:

• Use multipass mode (CLI --multipass, or freemkv-library max_retries ≥ 1) to retry bad ranges — freemkv reports good / recovered / unrecoverable sectors as it goes.
• In freemkv-library, set abort_on_lost_secs above 0 to tolerate a bounded amount of main-movie loss rather than failing on a disc that can’t be read perfectly.

Don’t keep retrying a dying disc

Repeatedly hammering the same bad sectors can push a drive into a fast-fail state where it stops attempting recovery entirely. If recovery stalls, let the drive cool down or eject and reload before trying again; don’t launch pass after pass back-to-back.

An interrupted rip

• CLI: Ctrl-C halts cleanly and preserves the mapfile. Re-running the same disc:// iso:// command resumes. A mux interrupted mid-write is not finalized (freemkv exits non-zero), so you never get a truncated MKV that looks complete.
• freemkv-library: /api/stop/{device} preserves staging; the rip resumes on the next disc insert or container restart. See Resume.

Raw or multipass flag rejected

--raw and --multipass describe how to read a drive: --raw leaves the sectors coming off the disc encrypted, and --multipass re-reads bad sectors over several passes. Both need a disc:// source and an iso:// destination, and each half is checked on its own.

• Wrong destination. freemkv rejects both flags for any destination other than iso:// (including mkv://, m2ts://, dir://, null://, stdio://, and network destinations), because ciphertext can’t be muxed and there is no sector image to recover into. Drop the flag, or change the destination to an ISO.
• Wrong source. Since 1.6.1 an iso:// destination no longer implies a disc — iso://In.iso iso://Out.iso decrypts an image you already have. There is no drive there to re-read or to leave encrypted, so both flags are rejected for any source that isn’t disc://. Drop the flag, or point the command at the disc in a drive.

Multiple titles to one file

Selecting more than one title (e.g. -t 1 -t 3) requires a directory destination; freemkv writes one file per title. Point the destination at a directory instead of a single file:

# directory destination, one file per title
freemkv disc:// mkv://out/ -t 1 -t 3

Checking versions

# CLI
freemkv version

# freemkv-library
curl -s http://<host>:8080/api/version