error codes

Error Codes

Every public API returns (or reports) a ChdError value instead of throwing. This page lists all values, their meaning, and where they are produced.

Value	GetMessage()	Produced when
Chderrnone	"No error"	Success.
Chderrnointerface	"No interface available"	(reserved for MAME API parity)
Chderroutofmemory	"Out of memory"	Image > 2 GiB for ReadAllBytes/Precache, or allocation failure.
Chderrinvalidfile	"Not a valid CHD file"	Bad magic, bad header length, or unreadable header.
Chderrinvalidparameter	"Invalid parameter"	Non-seekable/unreadable stream, buffer too small, out-of-range read args.
Chderrinvaliddata	"Invalid or corrupt data"	Header validation failures, corrupt map/metadata, malformed compressed hunk structure.
Chderrfilenotfound	"File not found"	Open(path) on a missing file.
Chderrrequiresparent	"Child CHD requires a parent"	Opening a child without a parent; reading a parent hunk with none attached.
Chderrfilenotwriteable	"File is not writable"	(reserved)
Chderrreaderror	"Read error"	IO failure while reading the stream (header, metadata, precache).
Chderrwriteerror	"Write error"	IO failure while writing extraction output.
Chderrcodecerror	"Codec error"	A codec slot is missing/uninitialized (e.g. secondary codec not set).
Chderrinvalidparent	"Invalid or incompatible parent CHD"	Supplied parent's hashes do not match the child's stored parent hashes.
Chderrhunkoutofrange	"Hunk index out of range"	ReadHunk with hunknum >= HunkCount.
Chderrdecompressionerror	"Decompression failed"	CRC mismatch after decompression, codec failure, or unexpected exception inside hunk decoding.
Chderrcompressionerror	"Compression failed"	(reader-side: decompression failure in ReadBlock; the encoder throws instead)
Chderrcantcreatefile	"Cannot create file"	(reserved)
Chderrcantverify	"Cannot verify CHD"	(reserved)
Chderrnotsupported	"Feature not supported"	(reserved)
Chderrmetadatanotfound	"Metadata not found"	GetMetadata found no entry matching the tag/index.
Chderrinvalidmetadatasize	"Invalid metadata size"	(reserved)
Chderrunsupportedversion	"Unsupported CHD version"	Version outside 1–5.
Chderrverifyincomplete	"Verification incomplete"	(reserved)
Chderrinvalidmetadata	"Invalid or corrupt metadata"	Combined-SHA1 (raw data + metadata) mismatch in deep verification.
Chderrinvalidstate	"Invalid state"	(reserved)
Chderroperationpending	"Operation already pending"	(reserved)
Chderrnoasyncoperation	"No async operation in progress"	(reserved)
Chderrunsupportedformat	"Unsupported format"	(reserved for unknown codec tags/unknown formats)
Chderrcannotopenfile	"Cannot open file"	Open(path) hit an IO/access error creating the FileStream.

Values marked (reserved) exist for MAME/libchdr API parity — they are defined with matching messages but are not currently produced by any code path. The enum intentionally mirrors the C chd_error list 1:1 (plus Chderrcannotopenfile).

---

Getting the message

using CHDSharp;

ChdError err = ChdFile.Open("missing.chd", out _);
Console.WriteLine(err.GetMessage());          // "File not found"
Console.WriteLine((int)err);                  // numeric value

The GetMessage() extension covers every value; unknown values fall back to "Unknown error (<value>)".

---

Error-handling patterns

// Open errors
var err = ChdFile.Open(path, out var chd);
switch (err)
{
    case ChdError.Chderrnone:
        break;
    case ChdError.Chderrfilenotfound:
    case ChdError.Chderrcannotopenfile:
        Console.WriteLine("Cannot open the file");
        return;
    case ChdError.Chderrrequiresparent:
        Console.WriteLine("This is a child CHD — supply its parent");
        return;
    case ChdError.Chderrinvalidparent:
        Console.WriteLine("The supplied parent does not match");
        return;
    default:
        Console.WriteLine(err.GetMessage());
        return;
}

// Read errors
var herr = chd!.ReadHunk(0, hunk);
if (herr == ChdError.Chderrdecompressionerror)
{
    // log + report; the library already logged the inner exception via ILogger
}

See Troubleshooting for the common error paths and their causes.