Improve error handling

DePasqualeOrg · DePasqualeOrg · commit 2b855bb0ef52 · 2026-01-06T20:40:21.000+01:00
diff --git a/Libraries/Embedders/Configuration.swift b/Libraries/Embedders/Configuration.swift
@@ -73,7 +73,7 @@ private class ModelTypeRegistry: @unchecked Sendable {
             creators[rawValue]
         }
         guard let creator else {
-            throw EmbedderError(message: "Unsupported model type.")
+            throw EmbedderError.unsupportedModelType(rawValue)
         }
         return try creator(configuration)
     }
diff --git a/Libraries/Embedders/EmbeddingModel.swift b/Libraries/Embedders/EmbeddingModel.swift
@@ -51,7 +51,8 @@ public actor ModelContainer {
         async let tokenizerConfigTask = loadTokenizerConfig(
             configuration: configuration, hub: hub)
 
-        self.model = try loadSynchronous(modelDirectory: modelDirectory)
+        self.model = try loadSynchronous(
+            modelDirectory: modelDirectory, modelName: configuration.name)
         self.pooler = loadPooling(modelDirectory: modelDirectory)
 
         let (tokenizerConfig, tokenizerData) = try await tokenizerConfigTask
diff --git a/Libraries/Embedders/Load.swift b/Libraries/Embedders/Load.swift
@@ -6,8 +6,51 @@ import MLX
 import MLXNN
 import Tokenizers
 
-struct EmbedderError: Error {
-    let message: String
+public enum EmbedderError: LocalizedError {
+    case unsupportedModelType(String)
+    case missingConfigurationFile(String, String)
+    case configurationFileError(String, String, Error)
+    case configurationDecodingError(String, String, DecodingError)
+    case missingTokenizerConfig
+
+    public var errorDescription: String? {
+        switch self {
+        case .unsupportedModelType(let type):
+            return "Unsupported model type: \(type)"
+        case .missingConfigurationFile(let file, let modelName):
+            return "Missing or unreadable configuration file '\(file)' for model '\(modelName)'"
+        case .configurationFileError(let file, let modelName, let error):
+            return "Error reading '\(file)' for model '\(modelName)': \(error.localizedDescription)"
+        case .configurationDecodingError(let file, let modelName, let decodingError):
+            let errorDetail = extractDecodingErrorDetail(decodingError)
+            return "Failed to parse \(file) for model '\(modelName)': \(errorDetail)"
+        case .missingTokenizerConfig:
+            return "Missing tokenizer configuration"
+        }
+    }
+
+    private func extractDecodingErrorDetail(_ error: DecodingError) -> String {
+        switch error {
+        case .keyNotFound(let key, let context):
+            let path = (context.codingPath + [key]).map { $0.stringValue }.joined(separator: ".")
+            return "Missing field '\(path)'"
+        case .typeMismatch(_, let context):
+            let path = context.codingPath.map { $0.stringValue }.joined(separator: ".")
+            return "Type mismatch at '\(path)'"
+        case .valueNotFound(_, let context):
+            let path = context.codingPath.map { $0.stringValue }.joined(separator: ".")
+            return "Missing value at '\(path)'"
+        case .dataCorrupted(let context):
+            if context.codingPath.isEmpty {
+                return "Invalid JSON"
+            } else {
+                let path = context.codingPath.map { $0.stringValue }.joined(separator: ".")
+                return "Invalid data at '\(path)'"
+            }
+        @unknown default:
+            return error.localizedDescription
+        }
+    }
 }
 
 func prepareModelDirectory(
@@ -53,20 +96,38 @@ public func load(
     // Start tokenizer loading asynchronously, then load model synchronously.
     // Both operations run in parallel because async let begins execution immediately.
     async let tokenizerTask = loadTokenizer(configuration: configuration, hub: hub)
-    let model = try loadSynchronous(modelDirectory: modelDirectory)
+    let model = try loadSynchronous(modelDirectory: modelDirectory, modelName: configuration.name)
     let tokenizer = try await tokenizerTask
 
     return (model, tokenizer)
 }
 
-func loadSynchronous(modelDirectory: URL) throws -> EmbeddingModel {
+func loadSynchronous(modelDirectory: URL, modelName: String) throws -> EmbeddingModel {
     // Load config.json once and decode for both base config and model-specific config
     let configurationURL = modelDirectory.appending(component: "config.json")
-    let configData = try Data(contentsOf: configurationURL)
-    let baseConfig = try JSONDecoder().decode(BaseConfiguration.self, from: configData)
+    let configData: Data
+    do {
+        configData = try Data(contentsOf: configurationURL)
+    } catch {
+        throw EmbedderError.configurationFileError(
+            configurationURL.lastPathComponent, modelName, error)
+    }
+    let baseConfig: BaseConfiguration
+    do {
+        baseConfig = try JSONDecoder().decode(BaseConfiguration.self, from: configData)
+    } catch let error as DecodingError {
+        throw EmbedderError.configurationDecodingError(
+            configurationURL.lastPathComponent, modelName, error)
+    }
 
     let modelType = ModelType(rawValue: baseConfig.modelType)
-    let model = try modelType.createModel(configuration: configData)
+    let model: EmbeddingModel
+    do {
+        model = try modelType.createModel(configuration: configData)
+    } catch let error as DecodingError {
+        throw EmbedderError.configurationDecodingError(
+            configurationURL.lastPathComponent, modelName, error)
+    }
 
     // load the weights
     var weights = [String: MLXArray]()
diff --git a/Libraries/Embedders/Tokenizer.swift b/Libraries/Embedders/Tokenizer.swift
@@ -45,7 +45,7 @@ func loadTokenizerConfig(configuration: ModelConfiguration, hub: HubApi) async t
     }
 
     guard let tokenizerConfig = try await config.tokenizerConfig else {
-        throw EmbedderError(message: "missing config")
+        throw EmbedderError.missingTokenizerConfig
     }
     let tokenizerData = try await config.tokenizerData
     return (tokenizerConfig, tokenizerData)
diff --git a/Libraries/MLXLLM/LLMModelFactory.swift b/Libraries/MLXLLM/LLMModelFactory.swift
@@ -480,9 +480,14 @@ public final class LLMModelFactory: ModelFactory {
         // Load config.json once and decode for both base config and model-specific config
         let configurationURL = modelDirectory.appending(component: "config.json")
         let configData: Data
-        let baseConfig: BaseConfiguration
         do {
             configData = try Data(contentsOf: configurationURL)
+        } catch {
+            throw ModelFactoryError.configurationFileError(
+                configurationURL.lastPathComponent, configuration.name, error)
+        }
+        let baseConfig: BaseConfiguration
+        do {
             baseConfig = try JSONDecoder().decode(BaseConfiguration.self, from: configData)
         } catch let error as DecodingError {
             throw ModelFactoryError.configurationDecodingError(
diff --git a/Libraries/MLXLMCommon/ModelFactory.swift b/Libraries/MLXLMCommon/ModelFactory.swift
@@ -7,6 +7,8 @@ import Tokenizers
 public enum ModelFactoryError: LocalizedError {
     case unsupportedModelType(String)
     case unsupportedProcessorType(String)
+    case missingConfigurationFile(String, String)
+    case configurationFileError(String, String, Error)
     case configurationDecodingError(String, String, DecodingError)
     case noModelFactoryAvailable
 
@@ -16,6 +18,10 @@ public enum ModelFactoryError: LocalizedError {
             return "Unsupported model type: \(type)"
         case .unsupportedProcessorType(let type):
             return "Unsupported processor type: \(type)"
+        case .missingConfigurationFile(let file, let modelName):
+            return "Missing or unreadable configuration file '\(file)' for model '\(modelName)'"
+        case .configurationFileError(let file, let modelName, let error):
+            return "Error reading '\(file)' for model '\(modelName)': \(error.localizedDescription)"
         case .noModelFactoryAvailable:
             return "No model factory available via ModelFactoryRegistry"
         case .configurationDecodingError(let file, let modelName, let decodingError):
diff --git a/Libraries/MLXVLM/VLMModelFactory.swift b/Libraries/MLXVLM/VLMModelFactory.swift
@@ -259,9 +259,14 @@ public final class VLMModelFactory: ModelFactory {
         // Load config.json once and decode for both base config and model-specific config
         let configurationURL = modelDirectory.appending(component: "config.json")
         let configData: Data
-        let baseConfig: BaseConfiguration
         do {
             configData = try Data(contentsOf: configurationURL)
+        } catch {
+            throw ModelFactoryError.configurationFileError(
+                configurationURL.lastPathComponent, configuration.name, error)
+        }
+        let baseConfig: BaseConfiguration
+        do {
             baseConfig = try JSONDecoder().decode(BaseConfiguration.self, from: configData)
         } catch let error as DecodingError {
             throw ModelFactoryError.configurationDecodingError(
@@ -287,7 +292,20 @@ public final class VLMModelFactory: ModelFactory {
             perLayerQuantization: baseConfig.perLayerQuantization)
 
         let tokenizer = try await tokenizerTask
-        let (processorConfigData, baseProcessorConfig) = try await processorConfigTask
+        let processorConfigData: Data
+        let baseProcessorConfig: BaseProcessorConfiguration
+        let processorConfigFilename: String
+        do {
+            (processorConfigData, baseProcessorConfig, processorConfigFilename) =
+                try await processorConfigTask
+        } catch let error as ProcessorConfigError {
+            if let decodingError = error.underlying as? DecodingError {
+                throw ModelFactoryError.configurationDecodingError(
+                    error.filename, configuration.name, decodingError)
+            }
+            throw ModelFactoryError.configurationFileError(
+                error.filename, configuration.name, error.underlying)
+        }
 
         // Override processor type based on model type for models that need special handling
         // Mistral3 models ship with "PixtralProcessor" in their config but need Mistral3Processor
@@ -308,19 +326,32 @@ public final class VLMModelFactory: ModelFactory {
 
 }
 
+/// Error wrapper that includes the filename for better error messages.
+private struct ProcessorConfigError: Error {
+    let filename: String
+    let underlying: Error
+}
+
 /// Loads processor configuration, preferring preprocessor_config.json over processor_config.json.
+/// Returns the data, decoded config, and the filename that was loaded.
+/// Throws ProcessorConfigError wrapping any underlying error with the filename.
 private func loadProcessorConfig(from modelDirectory: URL) async throws -> (
-    Data, BaseProcessorConfiguration
+    Data, BaseProcessorConfiguration, String
 ) {
     let processorConfigURL = modelDirectory.appending(component: "processor_config.json")
     let preprocessorConfigURL = modelDirectory.appending(component: "preprocessor_config.json")
     let url =
         FileManager.default.fileExists(atPath: preprocessorConfigURL.path)
         ? preprocessorConfigURL
         : processorConfigURL
-    let data = try Data(contentsOf: url)
-    let config = try JSONDecoder().decode(BaseProcessorConfiguration.self, from: data)
-    return (data, config)
+    let filename = url.lastPathComponent
+    do {
+        let data = try Data(contentsOf: url)
+        let config = try JSONDecoder().decode(BaseProcessorConfiguration.self, from: data)
+        return (data, config, filename)
+    } catch {
+        throw ProcessorConfigError(filename: filename, underlying: error)
+    }
 }
 
 public class TrampolineModelFactory: NSObject, ModelFactoryTrampoline {

Original file line number	Diff line number	Diff line change
`@@ -73,7 +73,7 @@ private class ModelTypeRegistry: @unchecked Sendable {`
`73`	`73`	`creators[rawValue]`
`74`	`74`	`}`
`75`	`75`	`guard let creator else {`
`76`		`- throw EmbedderError(message: "Unsupported model type.")`
	`76`	`+ throw EmbedderError.unsupportedModelType(rawValue)`
`77`	`77`	`}`
`78`	`78`	`return try creator(configuration)`
`79`	`79`	`}`
Original file line number	Diff line number	Diff line change
`@@ -45,7 +45,7 @@ func loadTokenizerConfig(configuration: ModelConfiguration, hub: HubApi) async t`
`45`	`45`	`}`
`46`	`46`
`47`	`47`	`guard let tokenizerConfig = try await config.tokenizerConfig else {`
`48`		`- throw EmbedderError(message: "missing config")`
	`48`	`+ throw EmbedderError.missingTokenizerConfig`
`49`	`49`	`}`
`50`	`50`	`let tokenizerData = try await config.tokenizerData`
`51`	`51`	`return (tokenizerConfig, tokenizerData)`