Enum FraiseQLError 

#[non_exhaustive]
pub enum FraiseQLError {
    Parse {
        message: String,
        location: String,
    },
    Validation {
        message: String,
        path: Option<String>,
    },
    UnknownField {
        field: String,
        type_name: String,
    },
    UnknownType {
        type_name: String,
    },
    Database {
        message: String,
        sql_state: Option<String>,
    },
    ConnectionPool {
        message: String,
    },
    Timeout {
        timeout_ms: u64,
        query: Option<String>,
    },
    Cancelled {
        query_id: String,
        reason: String,
    },
    Authorization {
        message: String,
        action: Option<String>,
        resource: Option<String>,
    },
    Authentication {
        message: String,
    },
    RateLimited {
        message: String,
        retry_after_secs: u64,
    },
    NotFound {
        resource_type: String,
        identifier: String,
    },
    Conflict {
        message: String,
    },
    Configuration {
        message: String,
    },
    Unsupported {
        message: String,
    },
    ServiceUnavailable {
        message: String,
        retry_after: Option<u64>,
    },
    Auth(Box<dyn Error + Send + Sync>),
    Webhook(Box<dyn Error + Send + Sync>),
    Observer(Box<dyn Error + Send + Sync>),
    File(FileError),
    Internal {
        message: String,
        source: Option<Box<dyn Error + Send + Sync>>,
    },
}

Main error type for FraiseQL operations.

All errors in the core library are converted to this type. Language bindings convert this to their native error types.

Error Categories

Errors are organized by domain:

GraphQL Errors

• Parse — Malformed GraphQL syntax
• Validation — Schema validation failures
• UnknownField — Field doesn’t exist on type
• UnknownType — Type doesn’t exist in schema

Database Errors

• Database — PostgreSQL/MySQL/SQLite errors (includes SQL state code)
• ConnectionPool — Connection pool exhausted or unavailable
• Timeout — Query exceeded configured timeout
• Cancelled — Query was cancelled by caller

Authorization/Security Errors

• Authorization — User lacks permission for operation
• Authentication — Invalid/expired JWT token
• RateLimited — Too many requests (includes retry-after)

Resource Errors

• NotFound — Resource doesn’t exist (404)
• Conflict — Operation would violate constraints (409)

Configuration Errors

• Configuration — Invalid setup/configuration
• Unsupported — Operation not supported by current database backend

Internal Errors

• Internal — Unexpected internal failures

Stability

This enum is marked #[non_exhaustive] to allow adding new error variants in future minor versions without breaking backward compatibility.

External match expressions must include a wildcard _ arm:

use fraiseql_error::FraiseQLError;

fn describe(e: &FraiseQLError) -> &'static str {
    match e {
        FraiseQLError::Parse { .. } => "parse error",
        FraiseQLError::Validation { .. } => "validation error",
        _ => "other error", // required: FraiseQLError is #[non_exhaustive]
    }
}

The following would not compile, because the #[non_exhaustive] attribute forces downstream crates to handle the possibility of new variants — a wildcard arm is required even when every currently-defined variant is enumerated:

use fraiseql_error::FraiseQLError;

fn describe(e: &FraiseQLError) -> &'static str {
    // Missing wildcard arm: rejected by rustc even though it lists
    // a few real variants — the `#[non_exhaustive]` attribute makes
    // the enum effectively open from any downstream crate's point
    // of view.
    match e {
        FraiseQLError::Parse { .. } => "parse",
        FraiseQLError::Validation { .. } => "validation",
        FraiseQLError::Database { .. } => "database",
    }
}

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.

Parse

GraphQL parsing error.

Fields

message: String

Error message describing the parse failure.

location: String

Location in the query where the error occurred.

Validation

GraphQL validation error.

Fields

message: String

Error message describing the validation failure.

path: Option<String>

Path to the field with the error (e.g., “user.posts.0.title”).

UnknownField

Unknown field error.

Fields

field: String

The field name that was not found.

type_name: String

The type on which the field was queried.

UnknownType

Unknown type error.

Fields

type_name: String

The type name that was not found.

Database

Database operation error.

Fields

message: String

Error message from the database.

sql_state: Option<String>

SQL state code if available (e.g., “23505” for unique violation).

ConnectionPool

Connection pool error.

Fields

message: String

Error message.

Timeout

Query timeout error.

Fields

timeout_ms: u64

Timeout duration in milliseconds.

query: Option<String>

The query that timed out (truncated if too long).

Cancelled

Query cancellation error.

Fields

query_id: String

Query identifier for tracking/logging.

reason: String

Reason for cancellation.

Authorization

Authorization error.

Fields

message: String

Error message.

action: Option<String>

The action that was denied.

resource: Option<String>

The resource that was being accessed.

Authentication

Authentication error.

Fields

message: String

Error message.

RateLimited

Rate limiting error.

Fields

message: String

Error message.

retry_after_secs: u64

Number of seconds to wait before retrying.

NotFound

Resource not found error.

Fields

resource_type: String

Type of resource (e.g., “User”, “Post”).

identifier: String

Identifier that was looked up.

Conflict

Conflict error.

Fields

message: String

Error message.

Configuration

Configuration error.

Fields

message: String

Error message.

Unsupported

Unsupported operation error.

Fields

message: String

Error message describing what is not supported.

ServiceUnavailable

The service is temporarily unavailable (e.g. tenant suspended).

Maps to HTTP 503. retry_after is the number of seconds to wait, if known.

Fields

message: String

Human-readable reason for the unavailability.

retry_after: Option<u64>

Number of seconds to wait before retrying, if known.

Auth(Box<dyn Error + Send + Sync>)

An authentication or authorisation error originating from the auth subsystem.

The boxed source is the subsystem-specific error type (e.g. fraiseql_auth::AuthError). To preserve subsystem vocabulary while keeping fraiseql-error a leaf crate, the boxed payload is type-erased here; subsystem crates provide their own impl From<SubsystemError> for FraiseQLError (the sqlx pattern).

#[source] is explicit: thiserror 2.x does not auto-detect a single tuple field as the source, and downstream chain-walkers (tracing, miette, anyhow) rely on Error::source() returning the underlying subsystem error rather than None.

Pattern-matching on the inner error

Because the payload is boxed and dyn-erased, downstream match statements cannot bind on subsystem variants directly. Recover the concrete type via std::error::Error::source + downcast_ref:

use std::error::Error;
use fraiseql_error::FraiseQLError;
use fraiseql_auth::AuthError;

if let FraiseQLError::Auth(_) = &err {
    if let Some(inner) = err.source().and_then(|s| s.downcast_ref::<AuthError>()) {
        match inner {
            AuthError::TokenExpired => {/* handle */},
            _ => {},
        }
    }
}

Webhook(Box<dyn Error + Send + Sync>)

A webhook-processing error originating from the webhook subsystem.

#[source] is explicit for the same reason as Self::Auth; see that variant for the downcast_ref recovery pattern on the boxed fraiseql_webhooks::WebhookError.

Observer(Box<dyn Error + Send + Sync>)

An observer subsystem error (event dispatch, action execution, retry exhaustion).

#[source] is explicit for the same reason as Self::Auth; see that variant for the downcast_ref recovery pattern on the boxed fraiseql_observers::ObserverError.

File(FileError)

A file-handling error (size limit, unsupported type, virus scan, quota).

Unlike Auth, Webhook, and Observer, the file-domain vocabulary lives inside fraiseql-error itself (crate::FileError) because no subsystem crate owns it — file operations are spread across fraiseql-storage and fraiseql-server/storage.

Internal

Internal error.

Fields

message: String

Error message.

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

Optional source error for debugging.

Implementations

impl FraiseQLError

pub fn parse(message: impl Into<String>) -> FraiseQLError

Create a parse error.

pub fn parse_at( message: impl Into<String>, location: impl Into<String>, ) -> FraiseQLError

Create a parse error with location.

pub fn validation(message: impl Into<String>) -> FraiseQLError

Create a validation error.

pub fn validation_at( message: impl Into<String>, path: impl Into<String>, ) -> FraiseQLError

Create a validation error with path.

pub fn database(message: impl Into<String>) -> FraiseQLError

Create a database error.

pub fn unauthorized(message: impl Into<String>) -> FraiseQLError

Create an authorization error.

pub fn not_found( resource_type: impl Into<String>, identifier: impl Into<String>, ) -> FraiseQLError

Create a not found error.

pub fn config(message: impl Into<String>) -> FraiseQLError

Create a configuration error.

pub fn internal(message: impl Into<String>) -> FraiseQLError

Create an internal error.

pub fn cancelled( query_id: impl Into<String>, reason: impl Into<String>, ) -> FraiseQLError

Create a cancellation error.

pub const fn is_client_error(&self) -> bool

Check if this is a client error (4xx equivalent).

Derived from Self::status_code so the answer stays consistent with the variant’s actual HTTP routing (notably for File(_), which straddles 4xx and 5xx after F050).

pub const fn is_server_error(&self) -> bool

Check if this is a server error (5xx equivalent).

Derived from Self::status_code for the same consistency reason as Self::is_client_error.

pub const fn is_retryable(&self) -> bool

Check if this error is retryable.

pub const fn status_code(&self) -> u16

Get HTTP status code equivalent.

Future variants

FraiseQLError is #[non_exhaustive]. The trailing _ => 500 arm is a deliberate safety net so a new variant added without updating this match still gets a defined (and safe) HTTP status — generic 500 Internal Server Error — rather than leaking implementation details to the client by returning the wrong code.

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

Get error code for GraphQL response.

Future variants

FraiseQLError is #[non_exhaustive]. The trailing _ arm returns "INTERNAL_SERVER_ERROR" so a new variant added without updating this match still receives a stable (if generic) error code.

pub fn unknown_field_with_suggestion( field: impl Into<String>, type_name: impl Into<String>, available_fields: &[&str], ) -> FraiseQLError

Create an unknown field error with helpful suggestions.

pub fn from_postgres_code( code: &str, message: impl Into<String>, ) -> FraiseQLError

Create a database error from PostgreSQL error code.

pub fn rate_limited_with_retry(retry_after_secs: u64) -> FraiseQLError

Create a rate limit error with retry information.

pub fn auth_error(reason: impl Into<String>) -> FraiseQLError

Create an authentication error with context.

Trait Implementations

impl Debug for FraiseQLError

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

Formats the value using the given formatter.

impl Display for FraiseQLError

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

Formats the value using the given formatter.

impl Error for FraiseQLError

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 FraiseQLError

fn from(e: Error) -> FraiseQLError

Converts to this type from the input type.

impl From<Error> for FraiseQLError

fn from(e: Error) -> FraiseQLError

Converts to this type from the input type.

impl From<FileError> for FraiseQLError

fn from(source: FileError) -> FraiseQLError

Converts to this type from the input type.

impl From<VarError> for FraiseQLError

fn from(e: VarError) -> FraiseQLError

Converts to this type from the input type.