# 13. Troubleshooting

Common messages, their meaning, and what to do.

## 13.1 Conversion Errors

| Message (as shown in the log) | Meaning | Action |
|--------------------------------|---------|--------|
| `Failed to convert '<file>': ERROR: couldn't find bin file [<path>]` | chdman cannot find a track file referenced by the cue (missing, wrong name, or on a different drive). The app logs a directory listing to help. | Verify the `.bin` files are next to the cue with matching names. Non-ASCII names/BOMs, wrong names and zero-padding mismatches are normally handled automatically; re-scan the folder. If the bracketed path looks like two paths joined together, see the note below. |
| `Failed to convert '<file>': file size (N bytes) is not divisible by any standard sector size (2048/2324/2336/2352/2368/2448). The file may be corrupt or truncated.` | The image size doesn't match any CD/DVD sector geometry. Raw CD dumps mislabelled as `.iso`/`.img` are detected by content and no longer reach this check, so this now means a genuinely damaged file. | Re-download or re-rip the image; verify with the original disc. |
| `<file> is named as an archive but contains a raw CD disc image; converting it as a CD.` / `... named as a compressed ISZ image but ...` | Informational. The extension disagreed with the content, and the content won. | Nothing to do — the conversion proceeds correctly. |
| `<file>: no writable location on the same volume for a generated cue; converting the image as-is.` | A raw CD image needs a generated cue, and chdman can only reach the image from a cue on the **same volume** — but no writable temp location exists there. | Free space on the image's own drive, or move the image to a drive where a temp folder can be created. |
| `The output folder is inside the source folder, so CHDs will be written alongside the originals.` | Informational. Converting in place is supported. | Nothing to do. An existing CHD of the same name is only replaced after a successful conversion. |
| `Files named after this disc already exist here; extracting into "<name>" so they are kept.` / `<name>.iso already exists here; extracting into "<name>" so the existing file is kept.` | Informational. Extracted output takes the CHD's base name, so it would have replaced files of the same name — most likely when extracting into the folder the CHDs already live in. The disc was written to a subfolder instead. | Nothing to do. The existing files are untouched and the new ones are in the named subfolder; a `.cue`/`.gdi` set there is still valid, because its track references are relative. |
| `this is part 1 of an N-part split image ... A part is missing or truncated` | The `.001`/`.i00` parts do not join to a whole number of sectors. | Re-download the complete set; all parts must be in the same folder. |
| `the image is split across N segments and <name>.i01 is not in the same folder` | A segmented ISZ is missing a piece. | Put every `.isz`/`.i01`/`.i02`… segment together. |
| `segment <name>.i01 belongs to a different ISZ image (volume serial number does not match)` | Segments from two different rips were mixed. | Collect the segments of one image together. |
| `the ISZ image is encrypted (AES-256) and this tool cannot decrypt it.` | The ISZ was saved with a password. | Open it in UltraISO with the password and save it as an ISO first. |
| `this is segment N of a split image, not the first one.` | A `.i01`/`.part02` piece was offered as an input instead of the `.isz`. | Convert the `.isz` first segment; the rest are found beside it. |
| `the ISZ decompressed to N bytes but its header declares M` / `the restored image does not match the checksum the ISZ header declares` / `the ECM file's checksum does not match the data it decoded to` | The compressed file is truncated or damaged. The partial output is deleted rather than converted, because a short image would convert and look fine. | Re-download the file. |
| `the decoded/decompressed/extracted image is not a whole number of 2352-byte CD sectors or 2048-byte data sectors...` | The image recovered from the ECM/ISZ/archive fits none of the sector layouts chdman can read (2048, 2324, 2336, 2352, 2368, 2448 bytes per sector). | The compressed source is truncated or damaged; re-download it. |
| `the .mdf data file was not found next to the .mds descriptor` | The descriptor's data file could not be located unambiguously. A `.mdf` **renamed with a decoration** (`Game (USA).mdf` beside `Game.mds`), one folder down, or a split `.i00` first volume is now found automatically; this message only appears when several equally plausible candidates exist (e.g. `Game (Disc 1).mdf` and `Game (Disc 2).mdf` beside `Game.mds`). | Keep exactly one data file per descriptor — rename the one that belongs to the `.mds`, or move the others elsewhere. |
| `<file> also converts to <name>.chd; skipping it because <other> already targets the same output file.` | Two inputs map to the same output name. | Informational, reported at batch start before any time is spent. Only one of them will survive as `<name>.chd` — rename an input if you need both. |

> **On "couldn't find bin file" with a doubled path.** chdman joins a cue's `FILE` entry to the cue's own directory unconditionally, so an absolute `FILE` path produces something like `C:\temp\x\D:\game.iso`. Generated cues therefore always use a relative path and are written on the image's own volume. Seeing a doubled path means a hand-written cue contains an absolute `FILE` line — make it relative to the cue.
| `Failed to convert '<file>': Unit size must be specified if no output parent CHD is supplied` | A `.raw` input was converted without a unit size. | Should not occur in current versions (`.raw` inputs get `-us 2352` automatically); if it does, use a `.cue` descriptor instead. |
| `Failed to convert '<file>': Compressing, 0.0% complete...` | (Old versions) a chdman progress line was shown instead of the real error. | Update the app; the real error line is now selected from the end of chdman's output. |
| `Failed to convert '<file>': Error creating CHD file (...): Unknown error` | chdman could not create the output file (drive issues, permissions, full disk). | Check the output drive is writable, has free space, and the path isn't overlong. |
| `TIMEOUT: Conversion of '<file>' exceeded N minute(s). Marking as failed.` | The per-file time limit fired. | Increase the limit (max 4 hours) or convert fewer/larger files at once. |
| `Failed to convert '<file>': chdman terminated abnormally (exit code -1073741795; 0xC000001D, STATUS_ILLEGAL_INSTRUCTION ...)` | Windows killed chdman before it could print anything. Most often the bundled build uses CPU instructions this computer lacks (older CPUs without SSE4.2/AVX); antivirus quarantine damage produces the same class of crash. The built-in CHDSharp encoder normally takes over automatically — this message is shown only when it could not produce a usable CHD either. | If you want the faster chdman path back, replace `chdman.exe`/`chdman_arm64.exe` with a build that matches your CPU (e.g. an official MAME tools release) and add an antivirus exclusion for it; otherwise the built-in encoder handles conversions. |
| `chdman.exe terminated abnormally during the startup check (...)` and a warning | Same crash as above, detected before the batch starts. Because the built-in CHDSharp encoder is always available, the batch continues and each file is encoded in-process. | No action needed for conversion. To restore the faster chdman path, use a CPU-compatible build as in the previous row. |
| `The output folder is not writable: <path>` | Detected before the batch starts: writing there needs administrator rights (e.g. inside `Program Files`). | Choose an output folder you can write to (Documents, a data drive); nothing was converted yet. |
| `chdman.exe cannot be opened - it is held with incompatible access by another process.` | Rare: something holds chdman with sharing that blocks even read access. A second app instance or a normal antivirus scan no longer triggers this. | Close other instances of the app and any antivirus scan in progress, then retry. |
| `<name> is a folder, not a disc image file - skipping.` | Something that looks like an image name (`Game.BIN.ISO`) is actually a directory. Folders are skipped instead of being handed to chdman ("Is a directory"). | Point the app at the files inside it, or rename the folder so it does not end in an image extension. |
| `PBPSharp: Extraction failed - ... TruncatedPsar (code 9)` / `<name> does not contain a complete PlayStation disc image (the PBP is truncated or incomplete) — skipping. Re-download the file.` | The PBP's PlayStation data area ends before any track index — the signature of a truncated download. User-data condition: logged without a bug report. | Re-download the `.pbp`. |
| `PBPSharp: Extraction failed - ... DecompressionError (code 8)` | A PSAR block failed to inflate as raw deflate and as a zlib-wrapped stream — the PBP's compressed data is damaged (a block cut short by an incomplete download, for example). | Re-download the `.pbp`. |
| `<name>.chd was already produced earlier in this batch; keeping the first one.` | Two inputs resolved to the same output CHD (an archive's contents are not known at the collision preflight, for example). The duplicate is detected before it is converted and skipped; the first product is kept, as intended. | Informational; nothing to do. Rename one input if both products are needed. |
| `CHDSharp could not read or write the image: ...` | The built-in encoder hit a device or permission error (drive unplugged, disk failing, full disk, denied access), not an encoder defect. | Check the source and output drives, free space and permissions, then retry. |
| `<name> is named .pbp but contains <a ZIP archive / a CISO image / ...>; extracting/decompressing it instead.` | The `.pbp` extension disagreed with the content. Instead of reporting "InvalidHeader", the file is routed by what its bytes actually are. | Nothing to do — the conversion proceeds from the real content. |
| `this file is already a CHD. Copy it to the output folder rather than converting it.` | An input (often an image renamed to `.iso`/`.bin`) already contains a CHD. Skipping is intentional so outputs cannot be reprocessed; the notice is excluded from bug reports. | Nothing to do. Copy the existing CHD to the output folder yourself if it belongs in the converted set. |
| A `.pbp` extracts but the log shows no game title / disc ID | The PARAM.SFO inside the PBP is missing or corrupt. Extraction no longer requires the SFO — only the metadata is empty. | Informational; the disc converts anyway. |
| `Retrying with createdvd (unrecognized track type)...` | A CD attempt failed; the app retries as DVD. | Usually succeeds automatically. If it fails again, force CD/DVD manually. |
| `chdman exited with code N but produced a valid output file...` | Non-zero exit but a valid output; treated as success. | Informational — nothing to do. |
| `Conversion of '<file>' failed because a drive or device is no longer available...` | chdman reported a Win32 "device does not exist" error: the source or output drive was unplugged or a network share dropped while converting. | Reconnect the drive, or copy the source file to a local drive and convert again. |

## 13.2 Archive Errors

| Message | Meaning | Action |
|---------|---------|--------|
| `... multi-part RAR with a missing volume ...` | A multi-part RAR (`.partNN.rar`, old-style `.rar` + `.rNN`, or a set renamed `.001`/`.002`) is missing one or more volumes, or the first volume is not beside the part that was offered. | Download all volumes of the set into the same folder. The app extracts the set from its first volume automatically; later parts are not converted separately. |
| `<name>.mds cannot be converted: the image's track data is encrypted (password-protected or TAGES)...` | The Daemon Tools MDS v2 descriptor was decrypted, but the track data itself is encrypted. | Re-save the image without a password in Daemon Tools/Alcohol, or convert it to ISO first. |
| `<name>.mds cannot be converted: the track data is encrypted and no password was supplied...` | The MDS v2/MDX image's track data needs a password, and the app cannot prompt for one. | Re-save the image without a password, or convert it with a tool that accepts the password. Images encrypted without a user password (TAGES-style) decode automatically. |
| MDS v2 / MDX images | Daemon Tools MDS v2 descriptors are decrypted and decompressed transparently; compressed and encrypted track data and single-file `.mdx` containers (of any size) are decoded automatically. | Nothing to do — conversion proceeds like any other image. |
| A `CHDStudio_Temp` folder appeared at a drive root | The system temp path was not usable for chdman (non-ASCII or near MAX_PATH) or its volume lacked the space, so the app staged work on that drive. The folder is removed once it is empty, after the batch and at the next startup. | Nothing to do; the folder is cleaned automatically. Free space on the system drive or an ASCII-safe `%TEMP%` keeps the fallback from being used at all. |
| `Skipping <name>.partNN.rar - part N of a multi-part RAR set; <name>.part01.rar extracts the whole set.` | Informational. The folder scan found every volume of a multi-part RAR; only the first is kept because it decodes the whole set. | Nothing to do. |
| `... Archive is encrypted ...` | The archive is password-protected. | Password-protected archives are not supported; extract manually first. |
| `... compression method that is not supported ...` | The ZIP uses Deflate64/LZMA/PPMd, which the extractor can't read. | Re-zip with standard Deflate, or extract manually first. |
| `... archive file may be corrupted or incomplete ...` | The archive failed CRC/structure checks. | Re-download the archive. |
| `No supported primary files found in archive.` | The archive contains no convertible image/descriptor (and no bare `.bin`). | Check the archive contents. |
| `... archive file appears to be incomplete ...` / `... could not validate referenced files ...` | Archive entries reference data files that aren't in the archive (split-bin sets, CRC-skipped entries). | Get the complete archive set; the app skips the entry with a warning instead of failing hard. |

## 13.3 CHD Extraction & Verification

| Message | Meaning | Action |
|---------|---------|--------|
| `Failed to open '<file>.chd': Not a valid CHD file` | The file isn't a CHD (bad magic). | The file is corrupt or misnamed; re-acquire it. |
| `Failed to open '<file>.chd': Invalid or corrupt data` | CHD structure is broken. | Re-acquire the file; verify it with `chdman verify`. |
| `Failed to open '<file>.chd': Cannot open file` | The file is locked/unreadable. | Close any program holding the file (emulator, antivirus scan) and retry. |
| `Built-in reader could not extract '<file>': ... Trying chdman...` | Informational: CHDSharp could not decode a hunk (corrupt/A/V CHD or reader limitation), so the app is retrying with chdman. Only a failure of that fallback is reported as a bug. | Nothing to do if a `Extracted ... using chdman fallback` line follows; otherwise re-acquire the file or verify it with `chdman verify`. |
| `Partial extraction: N file(s) remain in temp directory: <dir>` | A multi-track extraction failed partway; the temp dir is kept for inspection. | Check the listed `_extract_temp_*` folder, delete leftovers, and retry with a valid CHD. |
| `Failed to move file <path>: The process cannot access the file because it is being used by another process` | The move was blocked by a lock. | Current versions retry for ~45 s; if it still fails, close file-holding programs and retry. |

## 13.4 Environment & Startup

| Message | Meaning | Action |
|---------|---------|--------|
| `chdman.exe was not found, so conversions will run on the built-in CHDSharp encoder.` | Windows only: chdman is missing or was moved. Conversion still works on the built-in encoder. | Optional: keep `chdman.exe`/`chdman_arm64.exe` in the app folder to use the bundled native encoder. This notice never appears on Linux/macOS, where the built-in encoder is the normal path. |
| `chdman.exe is not compatible with this OS.` (Win32 error 193) | The exe cannot run on this Windows, or files from the win-arm64 release were copied into a win-x64 install (or vice versa). | Keep the two releases separate; use a chdman build for your Windows version. |
| Startup log `Process Architecture:` / `OS Architecture:` / `chdman executable:` / `CHDSharp encoder: built-in (always available)` lines | Informational: which build is running, what the machine is, which chdman binary was resolved, and that the in-process CHDSharp encoder is always present. On ARM64 machines the native chdman build is preferred even when the app itself runs emulated as x64. | Include these when reporting a crash — they make the report instantly classifiable. |
| Status bar CHDMAN indicator red (Windows) / gray (Linux/macOS) | Red: chdman is missing on Windows, so conversions run on the built-in CHDSharp encoder. Gray: chdman is optional on Linux/macOS and is never used for encoding. The CHDSharp indicator is always green because the encoder is built in. | No action needed — an encoder is always available. |
| `Selected temp root "X:\" is not writable, falling back to system temp` | The preferred temp drive can't be written (e.g. `E:\` is a card reader / locked). | Informational; the app uses the system temp instead. Free space on `C:` matters then. |
| `Another instance of CHDStudio is already running.` | Single-instance mutex. | The first instance is still running; close it first. |
| `Update check skipped: GitHub API rate limit exceeded.` | GitHub API 403/429 (shared IP). | Wait and restart; no action needed. |
| `Failed to record usage statistics: HTTP 429` | Stats endpoint rate-limited. | Expected; silently ignored (Debug log only). |

## 13.5 Data & Safety Questions

**Are my originals deleted automatically?** Only when **"Delete originals after a successful conversion"** is enabled, and only after the CHD was produced successfully. Cue-set deletions also remove referenced `.bin`/`.sub` files; CCD deletions remove `.img`/`.sub`/`.cdt`.

**What happens to temp files on crash?** Leftover `CHDStudio_Temp_*` folders are deleted at next startup.

**Where are the logs?** `%LocalAppData%\CHDStudio\logs` (daily files, 7 days retained). Click the **AppData** button in the title bar.

**Does the app phone home?** It sends: anonymous usage stats (application name + version, once per launch), bug reports for warning-level events (see [Bug Reporting System](09-bug-reporting.md)), and GitHub update checks. No personal data is collected (the bug report includes the Windows user name as `userInfo`).

**Why do some bugs keep showing the same message?** Corrupt input files (bad CHDs, incomplete archives) are user-data conditions — the app now excludes those messages from bug reports; the in-app log remains the source of truth for them.