Add failure diagnostics and tolerant metadata matching (v1.4.0)

- ChdContainer.LastError reports open/parse failures (CHDSharp errors, track/metadata parsing, missing parser, unrecognized file system, no-data-track hint)

- Open catches track/metadata parsing exceptions instead of crashing

- Invariant-culture WAV track index parsing

- Case-insensitive matching for well-known track types (AUDIO/MODE2/MODE_2/CDI/PAD), IP.BIN and PC Engine boot signatures

- Version bumped to 1.4.0; WhatsNew and package release notes updated

Author: drpetersonfernandes

VideoGameFileSystemParser/Parsers/ChdContainer.cs

@@ -49,6 +49,11 @@ private enum CueExportMode
     private Dictionary<int, byte[]>? _wavHeaders;
     private Dictionary<int, ulong>? _wavDataSizes;
 
+    /// <summary>
+    /// Gets the reason the most recent open or parse operation failed, or <c>null</c> if it succeeded.
+    /// </summary>
+    public string? LastError { get; private set; }
+
     /// <summary>
     /// Gets the read-only list of all file and directory entries in the container.
     /// </summary>
@@ -101,25 +106,38 @@ public ChdContainer(string chdPath)
     public bool Open(ConsoleType consoleType)
     {
         ConsoleType = consoleType;
+        LastError = null;
 
         var err = ChdFile.Open(_chdPath, out var chd);
         if (err != ChdError.Chderrnone || chd is null)
+        {
+            LastError = $"CHDSharp failed to open the file: {err} ({err.GetMessage()})";
             return false;
+        }
 
         _primaryChd = chd;
+        try
+        {
+            var unitBytes = chd.UnitBytes;
+            var reader = new SectorReader(chd, unitBytes);
+            UnitBytes = unitBytes;
+            HunkBytes = chd.HunkBytes;
+            VolumeSize = chd.TotalBytes;
+            VolumeName = Path.GetFileNameWithoutExtension(_chdPath);
 
-        var unitBytes = chd.UnitBytes;
-        var reader = new SectorReader(chd, unitBytes);
-        UnitBytes = unitBytes;
-        HunkBytes = chd.HunkBytes;
-        VolumeSize = chd.TotalBytes;
-        VolumeName = Path.GetFileNameWithoutExtension(_chdPath);
-
-        _readerPool.Add(reader);
-        HasDataTracks = reader.Tracks.Any(static t => t.IsDataTrack);
-        lock (_poolLock)
+            _readerPool.Add(reader);
+            HasDataTracks = reader.Tracks.Any(static t => t.IsDataTrack);
+            lock (_poolLock)
+            {
+                _availableReaders.Add(reader);
+            }
+        }
+        catch (Exception ex)
         {
-            _availableReaders.Add(reader);
+            _primaryChd.Dispose();
+            _primaryChd = null;
+            LastError = $"CHDSharp opened the file but track/metadata parsing failed: {ex.Message}";
+            return false;
         }
 
         return true;
@@ -132,6 +150,8 @@ public bool Open(ConsoleType consoleType)
     /// <returns><c>true</c> if parsing succeeded; otherwise <c>false</c>.</returns>
     public bool MountAndParse(ConsoleType consoleType)
     {
+        LastError = null;
+
         if (!Open(consoleType))
             return false;
 
@@ -164,11 +184,21 @@ or ConsoleType.GenericCueBinWav2352 or ConsoleType.GenericCueBinWav2048
 
         var parser = ParserFactory.CreateParser(consoleType, _readerPool[0]);
         if (parser is null)
+        {
+            LastError = $"No file system parser is available for console type '{consoleType}'.";
             return false;
+        }
 
         var parsedRoot = new FsNode();
         if (!parser.Parse(parsedRoot))
+        {
+            var noDataTracksHint = HasDataTracks
+                ? string.Empty
+                : " The CHD has no data tracks; it may not be a CD/disc image (it could be a hard-drive image).";
+            LastError =
+                $"The '{consoleType}' file system parser could not find a recognizable file system on this disc.{noDataTracksHint}";
             return false;
+        }
 
         BuildFromFsNode(parsedRoot);
 
@@ -536,15 +566,16 @@ CueExportMode.CueBin2048 or CueExportMode.CueIso2048
                 var dataFileExt = isIsoMode ? "iso" : "bin";
                 var dataFileName = $"{_cueStemName}.{dataFileExt}";
 
-                if (currentFile != dataFileName)
+                if (!string.Equals(currentFile, dataFileName, StringComparison.OrdinalIgnoreCase))
                 {
                     if (!freshFile)
                         sb.AppendLine();
                     sb.AppendLine(CultureInfo.InvariantCulture, $"FILE \"{dataFileName}\" BINARY");
                     currentFile = dataFileName;
                 }
 
-                var modeStr = t.TrackType.Contains("MODE2") || t.TrackType.Contains("CDI")
+                var modeStr = t.TrackType.Contains("MODE2", StringComparison.OrdinalIgnoreCase) ||
+                              t.TrackType.Contains("CDI", StringComparison.OrdinalIgnoreCase)
                     ? $"MODE2/{_cueSectorSize}"
                     : $"MODE1/{_cueSectorSize}";
 
@@ -578,7 +609,7 @@ CueExportMode.CueBin2048 or CueExportMode.CueIso2048
                 {
                     var wavFileName = $"{_cueStemName}_Track{trackNum:D2}.wav";
 
-                    if (currentFile != wavFileName)
+                    if (!string.Equals(currentFile, wavFileName, StringComparison.OrdinalIgnoreCase))
                     {
                         if (!freshFile)
                             sb.AppendLine();
@@ -597,7 +628,7 @@ CueExportMode.CueBin2048 or CueExportMode.CueIso2048
                 else
                 {
                     var containerFile = isIsoMode ? $"{_cueStemName}.iso" : $"{_cueStemName}.bin";
-                    if (currentFile != containerFile)
+                    if (!string.Equals(currentFile, containerFile, StringComparison.OrdinalIgnoreCase))
                     {
                         if (!freshFile)
                             sb.AppendLine();
@@ -696,7 +727,7 @@ private bool TryParseWavTrackIndex(string entryName, out int trackIndex)
         if (!entryName.EndsWith(suffix, StringComparison.OrdinalIgnoreCase)) return false;
 
         var numStr = entryName.Substring(prefix.Length, entryName.Length - prefix.Length - suffix.Length);
-        return int.TryParse(numStr, out trackIndex) && _wavHeaders.ContainsKey(trackIndex);
+        return int.TryParse(numStr, CultureInfo.InvariantCulture, out trackIndex) && _wavHeaders.ContainsKey(trackIndex);
     }
 
     private static byte[] BuildWavHeader(ulong pcmDataSize)

VideoGameFileSystemParser/Parsers/SectorReader.cs

@@ -440,7 +440,7 @@ private bool PrepareHunk(uint lba, out uint rawOffsetInHunk)
         var hunkNum = chdFrame / sectorsPerHunk;
         var sectorInHunk = chdFrame % sectorsPerHunk;
 
-        var needsSwap = CurrentTrack?.TrackType == "AUDIO";
+        var needsSwap = string.Equals(CurrentTrack?.TrackType, "AUDIO", StringComparison.OrdinalIgnoreCase);
 
         if (hunkNum != _cachedHunkNum || _cachedHunkSwapped != needsSwap)
         {
@@ -722,8 +722,9 @@ public static uint GetSectorDataOffset(TrackInfo? track)
     {
         if (track is null) return 16;
         if (!track.IsDataTrack) return 0;
-        if (track.TrackType.Contains("MODE2") || track.TrackType.Contains("MODE_2")) return 24;
-        if (track.TrackType.Contains("CDI")) return 24;
+        if (track.TrackType.Contains("MODE2", StringComparison.OrdinalIgnoreCase) ||
+            track.TrackType.Contains("MODE_2", StringComparison.OrdinalIgnoreCase)) return 24;
+        if (track.TrackType.Contains("CDI", StringComparison.OrdinalIgnoreCase)) return 24;
 
         return 16;
     }
@@ -774,7 +775,8 @@ internal static List<TrackInfo> ParseTracksWithLba(ChdFile chd, uint unitBytes)
                 Pregap = pregap,
                 Postgap = postgap,
                 TrackType = typeStr,
-                IsDataTrack = typeStr.Contains("MODE") || typeStr.Contains("CDI"),
+                IsDataTrack = typeStr.Contains("MODE", StringComparison.OrdinalIgnoreCase) ||
+                              typeStr.Contains("CDI", StringComparison.OrdinalIgnoreCase),
                 Metadata = metaText
             });
         }
@@ -804,7 +806,7 @@ internal static List<TrackInfo> ParseTracksWithLba(ChdFile chd, uint unitBytes)
         {
             foreach (var t in tracks)
             {
-                if (t.Metadata.Contains("PAD:"))
+                if (t.Metadata.Contains("PAD:", StringComparison.OrdinalIgnoreCase))
                 {
                     isGdrom = true;
                     break;

VideoGameFileSystemParser/Parsers/Systems/DreamcastAndOthers.cs

@@ -85,7 +85,8 @@ private bool HasIpBin(TrackInfo track)
 
         var sec = new byte[2048];
         var ok = _reader.ReadSector(track.StartLba, sec) &&
-                 Encoding.ASCII.GetString(sec, 0, IpBinSignature.Length) == IpBinSignature;
+                 string.Equals(Encoding.ASCII.GetString(sec, 0, IpBinSignature.Length), IpBinSignature,
+                     StringComparison.OrdinalIgnoreCase);
 
         _reader.Reset();
         return ok;

VideoGameFileSystemParser/Parsers/Systems/PcEngineCdParser.cs

@@ -220,7 +220,7 @@ private static bool HasBootSignature(byte[] sector)
             return false;
 
         var descriptor = Encoding.ASCII.GetString(sector, 0x20, Signature.Length);
-        if (descriptor == Signature)
+        if (string.Equals(descriptor, Signature, StringComparison.OrdinalIgnoreCase))
             return true;
 
         var gamesExpress = Encoding.ASCII.GetString(sector, 0, Math.Min(sector.Length, 128));

VideoGameFileSystemParser/VideoGameFileSystemParser.csproj

@@ -10,7 +10,7 @@
 
         <!-- NuGet Package Metadata -->
         <PackageId>VideoGameFileSystemParser</PackageId>
-        <Version>1.3.0</Version>
+        <Version>1.4.0</Version>
         <Description>Video game file system parsing library for console disc images. Supports ISO 9660, UDF, XDVDFS, OperaFS, CD-i, and other formats through CHD, ISO and raw sector readers.</Description>
         <Title>VideoGameFileSystemParser</Title>
         <Copyright>Copyright (c) 2026 Peterson Fernandes (drpetersonfernandes)</Copyright>
@@ -20,9 +20,9 @@
         <PackageIcon>icon\icon.png</PackageIcon>
         <RepositoryUrl>https://github.com/drpetersonfernandes/VideoGameFileSystemParser</RepositoryUrl>
         <PackageTags>chd;mame;iso9660;udf;xdvdfs;operafs;cdi;ps1;ps2;ps3;psp;xbox;dreamcast;retro;videogame;disc;filesystem;emulation;emulator;emulator-development;emulators;filesystem;filetree;parser;parsing;parsing-algorithm;parsing-engine;parsing-library;parsing-table;video-game</PackageTags>
-        <PackageReleaseNotes>v1.3.0: Updated the CHDSharp dependency from 1.2.0 to 1.4.3, picking up the latest CHD decoder fixes, performance work and CancellationToken-aware I/O APIs. No public API changes. Requires CHDSharp 1.4.3 or newer at runtime.</PackageReleaseNotes>
-        <AssemblyVersion>1.3.0</AssemblyVersion>
-        <FileVersion>1.3.0</FileVersion>
+        <PackageReleaseNotes>v1.4.0: Added ChdContainer.LastError with detailed open/parse failure diagnostics; Open now reports CHDSharp and track/metadata errors instead of returning silently. Invariant-culture WAV track index parsing and case-insensitive matching for well-known track types (AUDIO/MODE2/CDI/PAD), IP.BIN and PC Engine boot signatures. Includes the v1.3.0 CHDSharp 1.4.3 dependency update.</PackageReleaseNotes>
+        <AssemblyVersion>1.4.0</AssemblyVersion>
+        <FileVersion>1.4.0</FileVersion>
     </PropertyGroup>
 
     <ItemGroup>

WhatsNew.md

@@ -1,6 +1,21 @@
 # What's New in VideoGameFileSystemParser
 
-This file tracks the highlights of each release. The latest version is **v1.3.0**.
+This file tracks the highlights of each release. The latest version is **v1.4.0**.
+
+---
+
+## v1.4.0 — Failure diagnostics and tolerant metadata matching
+
+**Release date:** 2026
+
+### New features
+
+- **`ChdContainer.LastError`** — gets the reason the most recent open or parse operation failed, or `null` on success. `Open` and `MountAndParse` now report what went wrong (CHDSharp open failure with the CHDSharp error message, track/metadata parsing exceptions, missing parser for a console type, and unrecognized file systems) instead of only returning `false`. When the image has no data tracks, the parse-failure message now hints that the file may not be a CD/disc image.
+
+### Fixes
+
+- **Invariant-culture WAV track index parsing** — the virtual CUE/WAV export parses track indices from file names with `CultureInfo.InvariantCulture`, so numbers are read consistently regardless of the host locale.
+- **Tolerant matching for well-known metadata tokens** — track types (`AUDIO`, `MODE2`, `MODE_2`, `CDI`, `PAD:`), the Sega IP.BIN signature and the PC Engine boot signature are now compared case-insensitively; disc file/volume names keep their exact, ordinal matching.
 
 ---