error-handling.md

Error Handling

Overview

The crate uses a single error type, MuseError, for all operations. It is defined in the error module and uses the thiserror crate for automatic Display and Error trait implementations.

Error variants

Io

MuseError::Io(std::io::Error)

File system errors: file not found, permission denied, etc. Automatically converted from std::io::Error via From.

When it occurs: read_xml_file, read_json_file, write_xml_file, write_json_file.

Xml

MuseError::Xml(quick_xml::DeError)

XML deserialization errors: malformed XML, missing required elements, unexpected structure. Automatically converted from quick_xml::DeError.

When it occurs: from_xml, read_xml_file.

XmlSerialize

MuseError::XmlSerialize(quick_xml::SeError)

XML serialization errors. Automatically converted from quick_xml::SeError.

When it occurs: to_xml, write_xml_file.

Json

MuseError::Json(serde_json::Error)

JSON parse or serialization errors. Automatically converted from serde_json::Error.

When it occurs: from_json, to_json, read_json_file, write_json_file.

MissingSection

MuseError::MissingSection { section: String }

A required section (e.g. PatientDemographics, TestDemographics) was not found in the input.

Display: Missing required section: PatientDemographics

MissingElement

MuseError::MissingElement { section: String, element: String }

A required element within a section was not found.

Display: Missing required element in TestDemographics: DataType

InvalidValue

MuseError::InvalidValue { field: String, message: String }

A field value is out of range or otherwise invalid.

Display: Invalid value for SampleBase: must be positive

Base64Decode

MuseError::Base64Decode { lead_id: String, message: String }

Base64 decoding failed for a lead's waveform data.

Display: Base64 decode error for lead I: Invalid byte 255

When it occurs: decode_waveform_data, verify_lead_crc32.

Crc32Mismatch

MuseError::Crc32Mismatch { lead_id: String, expected: u32, actual: u32 }

The computed CRC32 of decoded waveform data does not match the stored LeadDataCRC32 value.

Display: CRC32 mismatch for lead I: expected 0x12345678, got 0x87654321

When it occurs: verify_lead_crc32.

UnsupportedFormat

MuseError::UnsupportedFormat(String)

An unsupported file format was encountered.

Display: Unsupported format: .csv

Handling errors

Match on specific variants

use ge_healthcare_muse::{io_xml, MuseError};
use std::path::Path;

match io_xml::read_xml_file(Path::new("ecg.xml")) {
    Ok(ecg) => {
        println!("Loaded: {}", ecg.patient_demographics.patient_id);
    }
    Err(MuseError::Io(e)) if e.kind() == std::io::ErrorKind::NotFound => {
        eprintln!("File not found");
    }
    Err(MuseError::Xml(e)) => {
        eprintln!("Invalid XML: {}", e);
    }
    Err(e) => {
        eprintln!("Error: {}", e);
    }
}

Propagate with ?

All functions that return Result<T, MuseError> work with the ? operator:

fn process_ecg(path: &std::path::Path) -> Result<(), MuseError> {
    let ecg = io_xml::read_xml_file(path)?;
    let json = io_json::to_json(&ecg)?;
    io_json::write_json_file(Path::new("output.json"), &ecg)?;
    Ok(())
}

Convert to other error types

MuseError implements std::error::Error, so it works with anyhow, eyre, and other error handling crates:

use anyhow::Result;

fn process(path: &std::path::Path) -> Result<()> {
    let ecg = io_xml::read_xml_file(path)?;  // MuseError -> anyhow::Error
    Ok(())
}

Error messages

All error variants implement Display with clear, descriptive messages:

Variant	Example message
Io	I/O error: No such file or directory
Xml	XML parse error: missing field 'PatientID'
XmlSerialize	XML serialization error: ...
Json	JSON error: expected value at line 1 column 1
MissingSection	Missing required section: PatientDemographics
MissingElement	Missing required element in TestDemographics: Site
InvalidValue	Invalid value for SampleBase: must be positive
Base64Decode	Base64 decode error for lead V1: Invalid byte 255
Crc32Mismatch	CRC32 mismatch for lead I: expected 0x12345678, got 0x87654321
UnsupportedFormat	Unsupported format: .csv