Enum FileError 

#[non_exhaustive]
pub enum FileError {
    TooLarge {
        size: usize,
        max: usize,
    },
    InvalidType {
        got: String,
        allowed: Vec<String>,
    },
    MimeMismatch {
        declared: String,
        detected: String,
    },
    Storage {
        message: String,
        source: Option<Box<dyn Error + Send + Sync>>,
    },
    Processing {
        message: String,
    },
    NotFound {
        id: String,
    },
    VirusDetected {
        details: String,
    },
    QuotaExceeded,
    PermissionDenied {
        message: String,
        source: Option<Box<dyn Error + Send + Sync>>,
    },
    IoError {
        message: String,
        source: Option<Box<dyn Error + Send + Sync>>,
    },
    InvalidKey {
        message: String,
    },
    NotImplemented {
        message: String,
    },
    Unsupported {
        message: String,
    },
    SizeLimitExceeded {
        message: String,
        limit: Option<u64>,
        actual: Option<u64>,
    },
    MimeTypeNotAllowed {
        message: String,
        mime: Option<String>,
    },
    Backend {
        message: String,
        source: Option<Box<dyn Error + Send + Sync>>,
    },
}

Errors that occur during file upload, validation, storage, or retrieval.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

TooLarge

The uploaded file exceeds the configured maximum size.

Fields

size: usize

Actual size of the uploaded file in bytes.

max: usize

Maximum allowed file size in bytes.

InvalidType

The file’s extension or declared MIME type is not on the allow-list.

Fields

got: String

The MIME type or extension that was supplied.

allowed: Vec<String>

The set of allowed MIME types or extensions.

MimeMismatch

The file’s declared MIME type does not match its detected MIME type.

This can indicate a spoofed Content-Type header.

Fields

declared: String

The MIME type stated by the client.

detected: String

The MIME type detected by content inspection.

Storage

An error occurred while writing to or reading from the backing storage system (e.g. local disk, object store).

Fields

message: String

Description of the storage failure.

source: Option<Box<dyn Error + Send + Sync>>

Optional chained error from the storage backend.

Processing

An error occurred while processing the file contents (e.g. image resizing, format conversion).

Fields

message: String

Description of the processing failure.

NotFound

The requested file does not exist in the storage backend.

Fields

id: String

Identifier of the file that was not found.

VirusDetected

A virus or malware scanner flagged the uploaded file.

Fields

details: String

Scanner-provided details about the detected threat (server-side only).

QuotaExceeded

The user or tenant has exhausted their file storage quota.

PermissionDenied

The backend refused the request because the caller lacks permission (e.g. an object-store bucket policy denied the operation, IAM credentials are missing the required action, the SAS token is expired).

Distinct from a missing-credentials authentication failure — those surface as crate::FraiseQLError::Authentication.

Fields

message: String

Description of the permission failure (server-side only; the HTTP body is generic).

source: Option<Box<dyn Error + Send + Sync>>

Optional chained error from the storage backend.

IoError

A low-level I/O failure occurred while talking to the storage backend (filesystem read/write error, socket failure, JSON-parse failure on a backend response).

Fields

message: String

Description of the I/O failure.

source: Option<Box<dyn Error + Send + Sync>>

Optional chained error from the storage backend.

InvalidKey

The caller supplied a key that fails validation (empty, path-traversal segment, leading / or \). User-fixable; HTTP 400.

Fields

message: String

Description of why the key was rejected.

NotImplemented

The requested operation is not implemented for this backend (e.g. list on GCS, presigned URLs without V4 signing on Azure). The capability exists in the API surface but is unimplemented.

Fields

message: String

Description of the unimplemented operation.

Unsupported

The requested operation is not supported by this backend at all (e.g. presigned URLs for the local filesystem, presign-PUT for the non-S3 enum variants).

Fields

message: String

Description of the unsupported operation.

SizeLimitExceeded

The upload exceeds the configured per-bucket size limit.

Distinct from Self::TooLarge, which is set by client-side validation against max_object_bytes. This variant is raised by the service layer when the limit is enforced post-upload (e.g. for streaming uploads where the total size is only known once the body has been read).

Fields

message: String

Description of the size-limit violation.

limit: Option<u64>

Configured maximum size in bytes, if known.

actual: Option<u64>

Actual size of the payload in bytes, if known.

MimeTypeNotAllowed

The uploaded content type is not on the per-bucket allow-list.

Distinct from Self::InvalidType, which is raised at extension / MIME-sniffing time. This variant is raised by the service layer against the configured allowed_mime_types list.

Fields

message: String

Description of the rejection.

mime: Option<String>

The rejected MIME type, if known.

Backend

A generic backend / infrastructure failure with no more-specific classification.

Used for object-store authentication setup failures (missing env vars, invalid credentials JSON), backend HTTP-request failures, configuration errors (s3 backend without bucket config), and database failures in the storage metadata layer. Returns HTTP 500.

Fields

message: String

Description of the backend failure.

source: Option<Box<dyn Error + Send + Sync>>

Optional chained error from the underlying SDK / IO call.

Implementations

impl FileError

pub const fn error_code(&self) -> &'static str

Returns a short, stable error code string suitable for API responses and structured logging.

pub const fn status_code(&self) -> u16

Returns the HTTP status code this variant maps to when surfaced through crate::FraiseQLError::File.

User-fixable validation failures map to 4xx; backend / infrastructure failures map to 5xx. The split here preserves what fraiseql-storage/src/routes/mod.rs::storage_error_response previously hard-coded via the code: Option<String> discriminator on the (now-deprecated) FraiseQLError::Storage variant:

• NotFound → 404 — backend reports object missing
• PermissionDenied → 403 — backend refuses the operation
• InvalidKey → 400 — caller supplied a malformed key
• IoError, Backend, NotImplemented, Unsupported, SizeLimitExceeded, MimeTypeNotAllowed → 500 — preserves the legacy behavior of FraiseQLError::Storage (which routed every code except not_found/permission_denied to 500 via storage_error_response)
• All other (pre-existing) variants — TooLarge, InvalidType, MimeMismatch, VirusDetected, QuotaExceeded, Storage, Processing — fall back to the FraiseQLError::File-level 400 via the wildcard arm so that pre-F050 callers see unchanged HTTP responses.

Trait Implementations

impl Debug for FileError

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

Formats the value using the given formatter.

impl Display for FileError

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

Formats the value using the given formatter.

impl Error for FileError

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<FileError> for FraiseQLError

fn from(source: FileError) -> Self

Converts to this type from the input type.