Haskell Domain Errors

Haskell Domain Errors

Errors are domain types, not strings. Each error constructor carries the structured context relevant to the failure. Rendering for humans and serialization for logs are separate concerns on top of that structured type. The error type is the data; how it surfaces (return value, effect, exception) is an orthogonal decision.

The pattern

{-# LANGUAGE DeriveGeneric #-}
{-# LANGUAGE DerivingStrategies #-}
{-# LANGUAGE LambdaCase #-}
{-# LANGUAGE OverloadedStrings #-}

import Data.Aeson (ToJSON(..), object, (.=))
import Data.Text (Text)
import qualified Data.Text as T
import GHC.Generics (Generic)

data RegistrationError
  = EmailAlreadyExists Email
  | InvalidEmailFormat Text          -- ^ the raw input that failed
  | PasswordTooShort Int Int         -- ^ received length, minimum required
  | DatabaseUnavailable Text         -- ^ driver message
  deriving stock (Eq, Generic)

-- Human-readable Show: ready for console, log line, or UI message.
instance Show RegistrationError where
  show = \case
    EmailAlreadyExists (Email e) ->
      "Email already registered: " <> T.unpack e
    InvalidEmailFormat raw ->
      "Invalid email format: " <> show raw
    PasswordTooShort got need ->
      "Password too short: got " <> show got
        <> " chars, need at least " <> show need
    DatabaseUnavailable reason ->
      "Database unavailable: " <> T.unpack reason

-- Structured JSON: tagged discriminator + payload, suitable for log aggregators.
instance ToJSON RegistrationError where
  toJSON = \case
    EmailAlreadyExists e ->
      object [ "error" .= ("email_already_exists" :: Text)
             , "email" .= e ]
    InvalidEmailFormat raw ->
      object [ "error" .= ("invalid_email_format" :: Text)
             , "input" .= raw ]
    PasswordTooShort got need ->
      object [ "error" .= ("password_too_short" :: Text)
             , "got"   .= got
             , "min"   .= need ]
    DatabaseUnavailable reason ->
      object [ "error"  .= ("database_unavailable" :: Text)
             , "reason" .= reason ]

Rules

1. Constructors carry structured context, not pre-formatted strings. PasswordTooShort 4 8, never PasswordError "got 4, need 8". If you concatenate early, the structure is lost downstream — and structured logs are the whole point.

2. Show is hand-written, producing a human-readable message. This breaks the Haskell convention that Show round-trips with Read, but Read is rarely used in practice and a human-friendly Show removes the need for a separate Display/Pretty instance for most cases. Make a conscious decision: if a type genuinely needs Read round-trip, keep Show derived and add a separate function (renderError :: MyError -> Text) for humans.

3. ToJSON uses an explicit tag + payload shape, not Aeson's default sum-type encoding. The default ({"tag": "EmailAlreadyExists", "contents": [...]}) couples the Haskell constructor name to the wire format — renaming a constructor becomes a breaking change for log consumers. Use a snake_case discriminator under a stable key like "error" (or "type" / "kind" if the project prefers).

4. FromJSON is optional. Errors that flow one-way out of the system (logs, HTTP responses, telemetry) only need ToJSON. Add FromJSON only when something genuinely needs to deserialize the error back — typically tests, or when the error crosses a process boundary and needs to be reconstructed.

5. Exception instance only when the error is thrown via throwIO. Errors that travel through Either or an Error effect should not have Exception derived. Mixing throw-style and return-style for the same type is a frequent source of confusion. Pick one channel per error type and stick with it.

6. Nest errors when layers compose. When a higher-level operation can fail because a lower-level one failed, wrap rather than flatten:

   data CheckoutError
     = CheckoutPaymentFailed PaymentError
     | CheckoutInventoryShort ProductId Int  -- requested
     | CheckoutCustomerBlocked CustomerId
   

   The Show and ToJSON instances delegate to the inner error's instances. This keeps each layer's error vocabulary focused while preserving the full chain of context.

7. Per-app consistency matters more than universal rules. The exact JSON shape, the discriminator key name, whether to include a "message" field with the human-readable form — these are project decisions. Pick a shape in the first module that needs error types and follow it everywhere in that project.

Choosing the error channel

For each error type, decide upfront which channel it travels through:

See haskell-effectful for the Error effect in practice, and haskell-logging for how domain errors flow into structured log payloads.