Error Handling

Mizu simplifies error handling by letting you return errors directly from handlers. This keeps your code clean and ensures consistent error responses across your entire application.

Error Handling Philosophy

In Mizu, error handling follows a simple principle: handlers return errors, the framework handles them. This means:

Your handlers focus on business logic
Errors flow up naturally through return err
One central error handler formats all responses
Panics are caught and treated like errors

Returning Errors from Handlers

Any handler can return an error to indicate something went wrong:

func getUser(c *mizu.Ctx) error {
    id := c.Param("id")

    user, err := findUser(id)
    if err != nil {
        // Just return the error - Mizu will handle it
        return err
    }

    return c.JSON(200, user)
}

Default Behavior

If you don’t configure a custom error handler, Mizu will:

Log the error with the request context
Return a 500 Internal Server Error to the client
Include a generic error message (no sensitive details exposed)

The ErrorHandler

Define a global error handler to customize how all errors are processed:

func errorHandler(c *mizu.Ctx, err error) {
    // Log the error
    c.Logger().Error("request failed", "error", err)

    // Send a response
    _ = c.JSON(500, map[string]string{
        "error": "internal server error",
    })
}

func main() {
    app := mizu.New()
    app.ErrorHandler(errorHandler)

    app.Get("/", handler)
    app.Listen(":3000")
}

The error handler should always send a response. If it doesn’t, the client will receive an empty response.

Custom Error Types

Create custom error types to carry additional information like HTTP status codes:

// HTTPError carries an HTTP status code with the error
type HTTPError struct {
    Code    int
    Message string
    Err     error // Original error (optional)
}

func (e *HTTPError) Error() string {
    if e.Err != nil {
        return fmt.Sprintf("%s: %v", e.Message, e.Err)
    }
    return e.Message
}

func (e *HTTPError) Unwrap() error {
    return e.Err
}

// Helper constructors
func NotFound(message string) *HTTPError {
    return &HTTPError{Code: 404, Message: message}
}

func BadRequest(message string) *HTTPError {
    return &HTTPError{Code: 400, Message: message}
}

func Unauthorized(message string) *HTTPError {
    return &HTTPError{Code: 401, Message: message}
}

Using Custom Errors in Handlers

func getUser(c *mizu.Ctx) error {
    id := c.Param("id")
    if id == "" {
        return BadRequest("user ID is required")
    }

    user, err := findUser(id)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return NotFound("user not found")
        }
        return err
    }

    return c.JSON(200, user)
}

Handling Custom Errors

func errorHandler(c *mizu.Ctx, err error) {
    // Check for HTTPError
    var httpErr *HTTPError
    if errors.As(err, &httpErr) {
        if httpErr.Code >= 500 {
            c.Logger().Error("server error", "code", httpErr.Code, "error", err)
        } else {
            c.Logger().Warn("client error", "code", httpErr.Code, "error", err)
        }

        _ = c.JSON(httpErr.Code, map[string]string{
            "error": httpErr.Message,
        })
        return
    }

    // Unknown error - treat as 500
    c.Logger().Error("unexpected error", "error", err)
    _ = c.JSON(500, map[string]string{
        "error": "internal server error",
    })
}

Error Wrapping with Context

Use Go’s error wrapping to add context as errors bubble up:

func getUserOrders(c *mizu.Ctx) error {
    userID := c.Param("id")

    user, err := findUser(userID)
    if err != nil {
        return fmt.Errorf("fetching user %s: %w", userID, err)
    }

    orders, err := findOrders(user.ID)
    if err != nil {
        return fmt.Errorf("fetching orders for user %s: %w", userID, err)
    }

    return c.JSON(200, orders)
}

Unwrapping in Error Handler

func errorHandler(c *mizu.Ctx, err error) {
    // Log the full error chain
    c.Logger().Error("request failed", "error", err)

    // Check for specific errors
    if errors.Is(err, sql.ErrNoRows) {
        _ = c.JSON(404, map[string]string{"error": "not found"})
        return
    }

    if errors.Is(err, context.DeadlineExceeded) {
        _ = c.JSON(504, map[string]string{"error": "request timeout"})
        return
    }

    _ = c.JSON(500, map[string]string{"error": "internal server error"})
}

Panic Recovery

Mizu automatically recovers from panics and converts them to errors. This prevents your server from crashing:

func riskyHandler(c *mizu.Ctx) error {
    // If this panics, Mizu catches it
    data := loadData()
    result := data[0] // Panic if data is empty!
    return c.JSON(200, result)
}

Panics are wrapped in *mizu.PanicError:

func errorHandler(c *mizu.Ctx, err error) {
    var panicErr *mizu.PanicError
    if errors.As(err, &panicErr) {
        c.Logger().Error("panic recovered",
            "value", panicErr.Value,
            "stack", string(panicErr.Stack),
        )
        _ = c.JSON(500, map[string]string{"error": "internal server error"})
        return
    }

    // Handle regular errors...
}

While Mizu recovers from panics, you should still write defensive code. Panics are expensive and should be exceptions, not the norm.

Best Practices

Do

// DO: Return errors, don't handle them inline
func handler(c *mizu.Ctx) error {
    data, err := fetchData()
    if err != nil {
        return err  // Let error handler deal with it
    }
    return c.JSON(200, data)
}

// DO: Use custom error types for client errors
return NotFound("user not found")
return BadRequest("invalid email format")

// DO: Wrap errors with context
return fmt.Errorf("fetching user %s: %w", id, err)

// DO: Log with structured fields
c.Logger().Error("failed", "error", err, "user_id", id)

Don’t

// DON'T: Send response AND return error
c.JSON(400, map[string]string{"error": "bad"})
return errors.New("bad request")  // Response already sent!

// DON'T: Expose internal errors to clients
return c.JSON(500, map[string]string{
    "error": err.Error(),  // May expose sensitive info!
})

// DON'T: Ignore errors
data, _ := fetchData()  // What if this fails?

Summary

Concept	Description
Return errors	Handlers return `error`, Mizu handles them
ErrorHandler	One global handler for all errors
Custom errors	Create types with status codes
Error wrapping	Use `%w` to add context
Panic recovery	Automatic, converts to `PanicError`

Overview

Getting Started

Core Concepts

Building Your App

Deployment

Learn More

Error Handling Philosophy

Returning Errors from Handlers

Default Behavior

The ErrorHandler

Custom Error Types

Using Custom Errors in Handlers

Handling Custom Errors

Error Wrapping with Context

Unwrapping in Error Handler

Panic Recovery

Best Practices

Do

Don’t

Summary

Next steps

Middleware

Logging

​Error Handling Philosophy

​Returning Errors from Handlers

​Default Behavior

​The ErrorHandler

​Custom Error Types

​Using Custom Errors in Handlers

​Handling Custom Errors

​Error Wrapping with Context

​Unwrapping in Error Handler

​Panic Recovery

​Best Practices

​Do

​Don’t

​Summary

​Next steps

Middleware

Logging

Error Handling Philosophy

Returning Errors from Handlers

Default Behavior

The ErrorHandler

Custom Error Types

Using Custom Errors in Handlers

Handling Custom Errors

Error Wrapping with Context

Unwrapping in Error Handler

Panic Recovery

Best Practices

Do

Don’t

Summary

Next steps