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)
}
*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: 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 |
Next steps