Enum Error 

pub enum Error {
    Malformed {
        message: String,
        file: &'static str,
        line: u32,
    },
    OutOfBounds {
        file: &'static str,
        line: u32,
    },
    NotSupported,
    Io(Error),
    Other(String),
    Goblin(Error),
    TypeNotFound(Token),
    TypeError(String),
    TypeMissingParent,
    TypeNotPrimitive,
    TypeConversionInvalid,
    RecursionLimit(usize),
    MarshallingError(String),
    DepthLimitExceeded(usize),
    GraphError(String),
    CannotModifyReplacedTable,
    ModificationInvalid(String),
    InvalidRid {
        table: TableId,
        rid: u32,
    },
    CrossReferenceError(String),
    HeapBoundsError {
        heap: String,
        index: u32,
    },
    ConflictResolution(String),
    ValidationStage1Failed {
        source: Box<Error>,
        message: String,
    },
    ValidationStage2Failed {
        errors: Vec<Error>,
        error_count: usize,
        summary: String,
    },
    ValidationRawFailed {
        validator: String,
        message: String,
    },
    ValidationOwnedFailed {
        validator: String,
        message: String,
    },
    ValidationEngineInitFailed {
        message: String,
    },
    InvalidToken {
        token: Token,
        message: String,
    },
    LayoutFailed(String),
    MmapFailed(String),
    FinalizationFailed(String),
    InvalidMnemonic(String),
    WrongOperandType {
        expected: String,
    },
    UnexpectedOperand,
    InvalidBranch(String),
    UndefinedLabel(String),
    DuplicateLabel(String),
    LockError(String),
    Configuration(String),
}

dotscope Error type.

The main error type for all operations in this crate. Provides detailed error information for file parsing, metadata validation, and disassembly operations.

Usage Examples

use dotscope::{Error, CilObject};

match CilObject::from_path(std::path::Path::new("tests/samples/crafted_2.exe")) {
    Ok(assembly) => println!("Loaded successfully"),
    Err(Error::NotSupported) => println!("File format not supported"),
    Err(Error::Malformed { message, .. }) => println!("Malformed: {}", message),
    Err(e) => println!("Error: {}", e),
}

The generic Error type, which provides coverage for all errors this library can potentially return.

This enum covers all possible error conditions that can occur during .NET assembly parsing, metadata analysis, and disassembly operations. Each variant provides specific context about the failure mode to enable appropriate error handling.

Error Categories

File Parsing Errors

• crate::Error::Malformed - Corrupted or invalid file structure
• crate::Error::OutOfBounds - Attempted to read beyond file boundaries
• crate::Error::NotSupported - Unsupported file format or feature

I/O and External Errors

• crate::Error::Io - Filesystem I/O errors
• crate::Error::Goblin - PE/ELF parsing errors from goblin crate

Type System Errors

• crate::Error::TypeNotFound - Requested type not found in type system
• crate::Error::TypeError - General type system operation error
• crate::Error::TypeMissingParent - Type inheritance chain broken
• crate::Error::TypeNotPrimitive - Expected primitive type
• crate::Error::TypeConversionInvalid - Invalid type conversion requested

Analysis Errors

• crate::Error::RecursionLimit - Maximum recursion depth exceeded
• crate::Error::DepthLimitExceeded - Maximum nesting depth exceeded in iterative parsing
• crate::Error::GraphError - Dependency graph analysis error

Thread Safety

This error enum is std::marker::Send and std::marker::Sync as all variants contain thread-safe types. This includes owned strings, primitive values, and errors from external crates that are themselves thread-safe. Errors can be safely passed between threads and shared across thread boundaries.

Variants

Malformed

The file is damaged and could not be parsed.

This error indicates that the file structure is corrupted or doesn’t conform to the expected .NET PE format. The error includes the source location where the malformation was detected for debugging purposes.

Fields

• message - Detailed description of what was malformed
• file - Source file where the error was detected
• line - Source line where the error was detected

Fields

message: String

The message to be printed for the Malformed error

file: &'static str

The source file in which this error occured

line: u32

The source line in which this error occured

OutOfBounds

An out of bound access was attempted while parsing the file.

This error occurs when trying to read data beyond the end of the file or stream. It’s a safety check to prevent buffer overruns during parsing. The error includes the source location where the out-of-bounds access was detected for debugging purposes.

Fields

• file - Source file where the error was detected
• line - Source line where the error was detected

Fields

file: &'static str

The source file in which this error occurred

line: u32

The source line in which this error occurred

NotSupported

This file type is not supported.

Indicates that the input file is not a supported .NET PE executable, or uses features that are not yet implemented in this library.

Io(Error)

File I/O error.

Wraps standard I/O errors that can occur during file operations such as reading from disk, permission issues, or filesystem errors.

Other(String)

Other errors that don’t fit specific categories.

NOTE: Prefer specific error types. Use this only for:

• Wrapping external library errors with context
• Temporary errors during development
• Truly miscellaneous errors

Goblin(Error)

Error from the goblin crate during PE/ELF parsing.

The goblin crate is used for low-level PE format parsing. This error wraps any failures from that parsing layer.

TypeNotFound(Token)

Failed to find type in TypeSystem.

This error occurs when looking up a type by token that doesn’t exist in the loaded metadata or type system registry.

The associated crate::metadata::token::Token identifies which type was not found.

TypeError(String)

General error during TypeSystem usage.

Covers various type system operations that can fail, such as type resolution, inheritance chain analysis, or generic instantiation.

TypeMissingParent

The parent of the current type is missing.

This error occurs when analyzing type inheritance and the parent type referenced by a type definition cannot be found or resolved.

TypeNotPrimitive

This type can not be converted to a primitive.

Occurs when attempting to convert a complex type to a primitive type representation, but the type is not compatible with primitive type semantics.

TypeConversionInvalid

The requested type conversion is not possible.

This error occurs when attempting type conversions that are semantically invalid in the .NET type system.

RecursionLimit(usize)

Recursion limit reached.

To prevent stack overflow during recursive operations like type resolution or dependency analysis, a maximum recursion depth is enforced. This error indicates that limit was exceeded.

The associated value shows the recursion limit that was reached.

MarshallingError(String)

Marshalling descriptor encoding error.

This error occurs when encoding marshalling information fails due to invalid or inconsistent marshalling descriptor data, such as sequential parameter constraints being violated.

The associated string contains details about what failed during encoding.

DepthLimitExceeded(usize)

To prevent resource exhaustion and stack overflow during iterative parsing operations, a maximum nesting depth is enforced. This error indicates that the depth limit was exceeded while parsing complex nested structures.

This applies to iterative stack-based parsing in:

• Signature type parsing (nested generic types, arrays, pointers)
• Custom attribute parsing (nested arrays, tagged objects)
• Any other iterative parser with explicit depth limiting

The associated value shows the nesting depth limit that was reached.

GraphError(String)

LoaderGraph error.

Errors related to dependency graph analysis and metadata loading order resolution. This can occur when circular dependencies are detected or when the dependency graph cannot be properly constructed.

CannotModifyReplacedTable

Cannot modify replaced table.

This error occurs when attempting to apply sparse modifications to a table that has been completely replaced.

ModificationInvalid(String)

Invalid modification operation.

This error occurs when attempting an operation that is not valid for the current state or context.

InvalidRid

Invalid RID for table during validation.

This error occurs when a RID is invalid for the target table, such as zero-valued RIDs or RIDs exceeding table bounds.

Fields

table: TableId

The table with the invalid RID

rid: u32

The invalid RID

CrossReferenceError(String)

Cross-reference validation failed.

This error occurs when validation detects broken cross-references between metadata tables.

HeapBoundsError

Heap bounds validation failed.

This error occurs when metadata heap indices are out of bounds for the target heap.

Fields

heap: String

The type of heap (strings, blobs, etc.)

index: u32

The out-of-bounds index

ConflictResolution(String)

Conflict resolution failed.

This error occurs when the conflict resolution system cannot automatically resolve detected conflicts.

ValidationStage1Failed

Stage 1 (raw) validation failed, preventing Stage 2 execution.

This error occurs when the first stage of validation (raw metadata validation) fails, causing the unified validation engine to terminate early without proceeding to Stage 2 (owned validation).

Fields

source: Box<Error>

The underlying error that caused Stage 1 to fail

message: String

Details about the Stage 1 failure

ValidationStage2Failed

Stage 2 (owned) validation failed with multiple errors.

This error occurs when Stage 2 validation (owned metadata validation) encounters multiple validation failures during parallel execution.

Fields

errors: Vec<Error>

All validation errors collected during Stage 2

error_count: usize

Number of errors for quick reference

summary: String

Summary of the validation failures

ValidationRawFailed

Raw validation failed for a specific validator.

This error occurs when a specific raw validator (Stage 1) fails during the validation process on CilAssemblyView data.

Fields

validator: String

Name of the validator that failed

message: String

Details about the validation failure

ValidationOwnedFailed

Owned validation failed for a specific validator.

This error occurs when a specific owned validator (Stage 2) fails during the validation process on CilObject data.

Fields

validator: String

Name of the validator that failed

message: String

Details about the validation failure

ValidationEngineInitFailed

Validation engine initialization failed.

This error occurs when the unified validation engine cannot be properly initialized due to invalid configuration or missing dependencies.

Fields

message: String

Details about the initialization failure

InvalidToken

Invalid token or token reference.

This error occurs when token format or cross-reference validation fails during either raw or owned validation stages.

Fields

token: Token

The token that failed validation

message: String

Details about the token validation failure

LayoutFailed(String)

Layout planning failed during binary generation.

This error occurs when the write planner cannot determine a valid layout for the output file, such as when the file would exceed configured size limits.

MmapFailed(String)

Memory mapping failed during binary reading or writing.

This error occurs when memory-mapped file operations fail, either for creating new mappings or accessing existing ones.

FinalizationFailed(String)

File finalization failed during binary writing.

This error occurs when the final step of writing (such as flushing, syncing, or closing the output file) fails.

InvalidMnemonic(String)

Invalid instruction mnemonic.

This error occurs when attempting to encode an instruction with a mnemonic that is not recognized in the CIL instruction set.

WrongOperandType

Wrong operand type for instruction.

This error occurs when the provided operand type doesn’t match the expected operand type for the instruction being encoded.

Fields

expected: String

The expected operand type

UnexpectedOperand

Unexpected operand provided.

This error occurs when an operand is provided for an instruction that doesn’t expect any operand.

InvalidBranch(String)

Invalid branch instruction or operand.

This error occurs when:

• Attempting to use the branch instruction encoding method with a non-branch instruction
• A branch instruction has an operand type not valid for branch offset encoding
• An invalid offset size is specified for branch instruction encoding

UndefinedLabel(String)

Undefined label referenced.

This error occurs when attempting to finalize encoding with unresolved label references.

DuplicateLabel(String)

Duplicate label definition.

This error occurs when attempting to define a label that has already been defined in the current encoding context.

LockError(String)

Lock or synchronization error.

This error occurs when synchronization primitives like barriers, locks, or cache locks fail during concurrent operations.

Examples

• Barrier wait failures during parallel loading
• Lock acquisition failures for cache updates
• Thread synchronization failures

Configuration(String)

Configuration or setup error.

This error occurs when there are issues with configuration, project setup, file paths, or other setup-related operations.

Examples

• Missing primary file specification
• Invalid search paths
• Duplicate assembly identities

Trait Implementations

impl Clone for Error

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.