Improve error handling on failure to open serialized file

Show extra message when there is no type trees
And avoid large unhelpful callstack when printing out errors if it is general Unknown error

Author: SkowronskiAndrew

Analyzer/AnalyzerTool.cs

@@ -6,6 +6,8 @@
 using UnityDataTools.Analyzer.SQLite.Parsers;
 using UnityDataTools.Analyzer.SQLite.Parsers.Models;
 using UnityDataTools.Analyzer.SQLite.Writers;
+using UnityDataTools.BinaryFormat;
+using UnityDataTools.FileSystem;
 
 namespace UnityDataTools.Analyzer;
 
@@ -74,8 +76,21 @@ public int Analyze(
                         ReportProgress(Path.GetRelativePath(path, file), i, files.Length);
                         countSuccess++;
                     }
+                    catch (SerializedFileOpenException e)
+                    {
+                        // Expected failure — the file content could not be parsed.
+                        // Don't print a stack trace; it adds no value for this known failure mode.
+                        EraseProgressLine();
+                        var relativePath = Path.GetRelativePath(path, file);
+                        Console.Error.WriteLine($"Failed to open: {relativePath}");
+                        var hint = SerializedFileDetector.GetOpenFailureHint(e.FilePath);
+                        if (hint != null)
+                            Console.Error.WriteLine(hint);
+                        countFailures++;
+                    }
                     catch (Exception e)
                     {
+                        // Unexpected failure (SQL error, I/O error, bug, etc.) — print full details.
                         EraseProgressLine();
                         var relativePath = Path.GetRelativePath(path, file);
                         Console.Error.WriteLine($"Failed to process: {relativePath}");

TextDumper/TextDumperTool.cs

@@ -49,7 +49,7 @@ public int Dump(string path, string outputPath, bool skipLargeArrays, long objec
                 Console.WriteLine("UnityDataTool only supports binary-format SerializedFiles.");
                 return 1;
             }
-            else if (SerializedFileDetector.TryDetectSerializedFile(path, out var fileInfo))
+            else if (SerializedFileDetector.TryDetectSerializedFile(path, out _))
             {
                 // The input is a binary SerializedFile; dump it directly.
                 try
@@ -59,21 +59,20 @@ public int Dump(string path, string outputPath, bool skipLargeArrays, long objec
                         OutputSerializedFile(path, objectId);
                     }
                 }
-                catch (Exception e)
+                catch (SerializedFileOpenException)
                 {
-                    PrintExceptionIfUseful(e);
-
-                    // Post-analysis: check if the failure is due to missing TypeTrees.
-                    if (SerializedFileDetector.TryParseMetadata(path, fileInfo, out var metadata, out _))
+                    var hint = SerializedFileDetector.GetOpenFailureHint(path);
+                    if (hint != null)
                     {
-                        if (!metadata.EnableTypeTree)
-                        {
-                            Console.WriteLine();
-                            Console.WriteLine("Note: This file does not have TypeTrees and can only be opened if all the types it");
-                            Console.WriteLine("uses exactly match the types available inside the build of UnityFileSystemApi being used.");
-                        }
+                        Console.WriteLine();
+                        Console.WriteLine(hint);
                     }
-
+                    return 1;
+                }
+                catch (Exception e)
+                {
+                    Console.WriteLine($"Error: {e.GetType()}: {e.Message}");
+                    Console.WriteLine(e.StackTrace);
                     return 1;
                 }
             }
@@ -86,26 +85,14 @@ public int Dump(string path, string outputPath, bool skipLargeArrays, long objec
         }
         catch (Exception e)
         {
-            PrintExceptionIfUseful(e);
+            Console.WriteLine($"Error: {e.GetType()}: {e.Message}");
+            Console.WriteLine(e.StackTrace);
             return 1;
         }
 
         return 0;
     }
 
-    static void PrintExceptionIfUseful(Exception e)
-    {
-        // Avoid printing noisy messages if it is just the generic "we don't know why it failed"
-        // fallback in UnityFileSystem.HandleErrors
-        if (e.GetType().ToString() != "System.Exception")
-            Console.Write($"Error: {e.GetType()}: ");
-        if (!e.Message.Contains("Unknown error"))
-            Console.WriteLine(e.Message);
-        var stackTrace = e.StackTrace;
-        if (!stackTrace.Contains("UnityFileSystem.HandleErrors"))
-            Console.WriteLine(e.StackTrace);
-    }
-
 
     void RecursiveDump(TypeTreeNode node, ref long offset, int level, int arrayIndex = -1)
     {

UnityBinaryFormat/SerializedFileDetector.cs

@@ -594,6 +594,25 @@ public static bool TryParseMetadata(string filePath, SerializedFileInfo headerIn
         }
     }
 
+    /// <summary>
+    /// Returns a diagnostic hint explaining why a SerializedFile may have failed to open,
+    /// or null if no specific diagnosis is available.
+    /// Currently detects the common case of missing TypeTrees (player builds compiled
+    /// without type information, which the DLL reports as a generic unknown error).
+    /// </summary>
+    /// <param name="path">Real filesystem path to the file that failed to open.</param>
+    public static string GetOpenFailureHint(string path)
+    {
+        if (TryDetectSerializedFile(path, out var fileInfo) &&
+            TryParseMetadata(path, fileInfo, out var metadata, out _) &&
+            !metadata.EnableTypeTree)
+        {
+            return "Note: This file does not have TypeTrees and can only be opened if all the " +
+                   "types it uses exactly match the types in the build of UnityFileSystemApi being used.";
+        }
+        return null;
+    }
+
     /// <summary>
     /// Parses the TypeTree and other arrays that are stored in the metadata,
     /// </summary>

UnityFileSystem/SerializedFileOpenException.cs

@@ -0,0 +1,16 @@
+using System;
+
+namespace UnityDataTools.FileSystem;
+
+/// <summary>
+/// Thrown when a SerializedFile cannot be opened, typically due to a content-related
+/// parsing failure (e.g. type mismatch, missing TypeTrees) rather than an I/O error.
+/// </summary>
+public class SerializedFileOpenException : Exception
+{
+    public string FilePath { get; }
+
+    public SerializedFileOpenException(string filePath)
+        : base($"Failed to open serialized file: \"{filePath}\"")
+        => FilePath = filePath;
+}

UnityFileSystem/UnityFileSystem.cs

@@ -47,6 +47,10 @@ public static UnityFile OpenFile(string path)
     public static SerializedFile OpenSerializedFile(string path)
     {
         var r = DllWrapper.OpenSerializedFile(path, out var handle);
+
+        if (r == ReturnCode.UnknownError)
+            throw new SerializedFileOpenException(path);
+
         UnityFileSystem.HandleErrors(r, path);
 
         return new SerializedFile() { m_Handle = handle };