# Troubleshooting

> Fixes for the most common freemkv and autorip problems. No drives detected, missing decryption keys, bad sectors, interrupted rips, and capturing a debug log.

Source: https://freemkv.org/docs/troubleshooting/

Fixes for the problems reported most often with freemkv and autorip. 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](https://freemkv.org/docs/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](https://freemkv.org/docs/changelog/) and update before digging further. You can confirm your running version from the [Checking versions](#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`):

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

In autorip, 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](https://freemkv.org/docs/platforms-windows/), [macOS](https://freemkv.org/docs/platforms-macos/), or [Linux](https://freemkv.org/docs/platforms-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.

> **Note: `--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](https://freemkv.org/docs/cli/) for the exact accepted flag set.

## macOS: "app is damaged" / can't open

freemkv isn't notarized yet, so macOS Gatekeeper blocks anything you download until you allow it once.

1. Double-click the app. It refuses — the dialog says macOS "could not verify" it. Click **Done**.
2. Open **System Settings → Privacy & Security** and scroll down. There is now a line naming freemkv, with an **Open Anyway** button. Click it and confirm.

That's a one-time step per download.

Older guides (including earlier versions of this page) say to right-click the app and choose **Open**. **macOS 15 Sequoia removed that shortcut** — the blocked dialog no longer offers anything but **Done**, and Open Anyway in System Settings is the only route.

This applies to the **CLI binary too**, not just the desktop app: a downloaded `freemkv` is quarantined the same way and is refused the first time you run it. Allow it in System Settings as above, or strip the quarantine flag yourself:

```bash
xattr -d com.apple.quarantine ./freemkv
```

See [macOS](https://freemkv.org/docs/platforms-macos/) for the full walkthrough.

## No drives detected in autorip

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.

```yaml
services:
  autorip:
    # 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](https://freemkv.org/docs/autorip/#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:

  ```bash
  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](https://freemkv.org/docs/decryption-keys/)** covers both options for the CLI and for autorip.

## 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 autorip `max_retries = 0`): no retries; a read error fails the rip.
- **Multipass** (CLI `--multipass`, or autorip `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](https://freemkv.org/docs/how-recovery-works/).

Tips:

- Use multipass mode (CLI `--multipass`, or autorip `max_retries ≥ 1`) to retry bad ranges — freemkv reports good / recovered / unrecoverable sectors as it goes.
- In autorip, 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.

> **Caution: 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.
- **autorip:** `/api/stop/{device}` preserves staging; the rip resumes on the next disc insert or container restart. See [Resume](https://freemkv.org/docs/autorip/#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:

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

## Checking versions

```bash
# CLI
freemkv version
```

```bash
# autorip
curl -s http://<host>:8080/api/version
```