Error Handling
MuxMaster provides a structured approach to error handling that eliminates boilerplate in individual handlers while giving you full control over how errors are serialized and logged.
Table of Contents
- The Problem with Standard Handlers
- HandlerFuncE
- HTTPError
- The Default Error Handler
- Custom Error Handler
- Error-Returning Method Variants
- Custom 404 and 405 Handlers
- Panic Recovery
- Patterns and Best Practices
The Problem with Standard Handlers
A http.HandlerFunc has no return value, so error handling is manual:
mux.GET("/users/:id", func(w http.ResponseWriter, r *http.Request) {
id, err := strconv.Atoi(muxmaster.PathParam(r, "id"))
if err != nil {
http.Error(w, "bad request", http.StatusBadRequest)
return
}
user, err := db.FindUser(id)
if err != nil {
http.Error(w, "not found", http.StatusNotFound)
return
}
if err := json.NewEncoder(w).Encode(user); err != nil {
log.Printf("encode error: %v", err)
}
})
Every handler repeats the same pattern: check error, write response, return. The error format (plain text in this case) must be kept consistent manually across all handlers.
HandlerFuncE
HandlerFuncE extends the standard handler signature with an error return:
type HandlerFuncE func(http.ResponseWriter, *http.Request) error
Handlers return nil on success, or an error to be handled centrally:
mux.GETE("/users/:id", func(w http.ResponseWriter, r *http.Request) error {
id, err := muxmaster.ParamsFromContext(r.Context()).Int("id")
if err != nil {
return muxmaster.Error(http.StatusBadRequest, err)
}
user, err := db.FindUser(id)
if err != nil {
return muxmaster.Error(http.StatusNotFound, errors.New("user not found"))
}
return muxmaster.JSON(w, http.StatusOK, user)
})
The same pattern applies to every HTTP method: GETE, POSTE, PUTE, PATCHE, DELETEE, HEADE, OPTIONSE, QUERYE.
HTTPError
muxmaster.Error(code, err) wraps an error with an HTTP status code:
// Create an HTTPError
err := muxmaster.Error(http.StatusNotFound, errors.New("user not found"))
// Check status code
var he muxmaster.HTTPError
if errors.As(err, &he) {
fmt.Println(he.StatusCode()) // 404
}
HTTPError is an interface:
type HTTPError interface {
error
StatusCode() int
}
Your ErrorHandler can recognise any error that implements this interface with errors.As, including custom implementations:
type ValidationError struct {
Field string
Message string
}
func (e *ValidationError) Error() string { return e.Field + ": " + e.Message }
func (e *ValidationError) StatusCode() int { return http.StatusUnprocessableEntity }
The Default Error Handler
When no ErrorHandler is set, every non-nil error returned by a HandlerFuncE produces the same response: 500 Internal Server Error with the plain-text body Internal Server Error. The status code carried by an HTTPError and the error message are not used, so no error detail reaches the client. Set an ErrorHandler to map HTTPError values to their status codes.
The handler is read from the configuration snapshot taken on the first request; see Configuration.
Custom Error Handler
Set mux.ErrorHandler to take over all error responses globally:
mux.ErrorHandler = func(w http.ResponseWriter, r *http.Request, err error) {
code := http.StatusInternalServerError
msg := "internal server error"
var he muxmaster.HTTPError
if errors.As(err, &he) {
code = he.StatusCode()
msg = err.Error()
} else {
// Log unexpected errors; do not leak internal details to the client
log.Printf("unhandled error [%s %s]: %v", r.Method, r.URL.Path, err)
}
muxmaster.JSON(w, code, map[string]string{"error": msg})
}
The ErrorHandler is called for every HandlerFuncE that returns a non-nil error, across the entire mux and all its groups.
Structured error responses
For APIs that need machine-readable errors:
type APIError struct {
Code int `json:"code"`
Message string `json:"message"`
Detail string `json:"detail,omitempty"`
}
mux.ErrorHandler = func(w http.ResponseWriter, r *http.Request, err error) {
apiErr := APIError{
Code: http.StatusInternalServerError,
Message: "internal server error",
}
var he muxmaster.HTTPError
if errors.As(err, &he) {
apiErr.Code = he.StatusCode()
apiErr.Message = err.Error()
}
var ve *ValidationError
if errors.As(err, &ve) {
apiErr.Detail = "field: " + ve.Field
}
muxmaster.JSON(w, apiErr.Code, apiErr)
}
Error-Returning Method Variants
Eight methods have an error-returning helper:
| Standard | Error-returning |
|---|---|
mux.GET |
mux.GETE |
mux.POST |
mux.POSTE |
mux.PUT |
mux.PUTE |
mux.PATCH |
mux.PATCHE |
mux.DELETE |
mux.DELETEE |
mux.HEAD |
mux.HEADE |
mux.OPTIONS |
mux.OPTIONSE |
mux.QUERY |
mux.QUERYE |
CONNECT and TRACE have none; use mux.HandleE(http.MethodConnect, path, h) or mux.HandleE(http.MethodTrace, path, h).
The same variants exist on *Group:
api := mux.Group("/api/v1")
api.POSTE("/users", createUser)
api.GETE("/users/:id", getUser)
api.DELETEE("/users/:id", deleteUser)
Custom 404 and 405 Handlers
Not Found (404)
Called when no route matches the request path. When NotFound is nil, the router uses http.NotFound (plain-text 404 page not found).
mux.NotFound = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
muxmaster.JSON(w, http.StatusNotFound, map[string]string{
"error": "the requested resource does not exist",
"path": r.URL.Path,
})
})
Middleware wrapping:
The NotFound handler is wrapped by any global middleware registered via Use(). The wrapper is applied dynamically: if you call Use() after assigning NotFound, the existing 404 handler will be re-wrapped with the new middleware chain. This ensures that logging, authentication, and other cross-cutting concerns apply to 404 responses.
Method Not Allowed (405)
Called when the path is registered for at least one method, but not the requested method. MuxMaster sets the Allow header automatically:
mux.MethodNotAllowed = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
allowed := w.Header().Get("Allow")
muxmaster.JSON(w, http.StatusMethodNotAllowed, map[string]string{
"error": "method not allowed",
"allowed": allowed,
})
})
To enable 405 responses, HandleMethodNotAllowed must be true (the default). When MethodNotAllowed is nil, the router writes 405 Method Not Allowed as plain text with the Allow header and X-Content-Type-Options: nosniff.
The automatic OPTIONS response and the router's own redirects are wrapped by Use() middleware in the same way.
Middleware wrapping:
Like NotFound, the MethodNotAllowed handler is wrapped by global middleware registered via Use(). The wrapper is applied dynamically, so adding middleware after assigning MethodNotAllowed will cause existing 405 responses to be re-wrapped with the new chain. This ensures that rate-limiting, logging, authentication, and other policies apply uniformly to 405 errors.
Panic Recovery
MuxMaster does not recover panics unless you ask it to. Without recovery, net/http recovers the panic itself, logs it and closes the connection, so the client gets no normal response. Use middleware.RecovererWithLogger to log the panic and answer with a plain 500 Internal Server Error:
mux.Use(middleware.RecovererWithLogger(slog.Default())) // Handle routes registered after this call
// or
mux.Pre(middleware.RecovererWithLogger(slog.Default())) // every request, including HandleFast routes
RecovererWithLogger writes its 500 response only if the handler has not already sent a status or body bytes; otherwise it leaves the response as the handler left it. middleware.Recoverer() is deprecated and equivalent to RecovererWithLogger(slog.Default()).
For custom panic handling, set mux.PanicHandler. It recovers panics from Pre middleware, Use middleware and the handlers of both Handle and HandleFast routes. A RecovererWithLogger registered inside it (with Pre or Use) catches a panic first, in which case PanicHandler is not called:
mux.PanicHandler = func(w http.ResponseWriter, r *http.Request, rcv any) {
log.Printf("panic recovered [%s %s]: %v\n%s",
r.Method, r.URL.Path, rcv, debug.Stack())
muxmaster.JSON(w, http.StatusInternalServerError, map[string]string{
"error": "an unexpected error occurred",
})
}
PanicHandler receives:
w http.ResponseWriter— the response writerr *http.Request— the request that caused the panicrcv any— the value passed topanic()
PanicHandler must not panic itself: a second panic is not recovered by MuxMaster and reaches net/http, which closes the connection.
Patterns and Best Practices
Wrap sentinel errors early
Define your domain errors using muxmaster.Error at the service boundary, so handlers never need to know status codes:
// In your repository or service layer
var ErrUserNotFound = muxmaster.Error(http.StatusNotFound, errors.New("user not found"))
var ErrUserExists = muxmaster.Error(http.StatusConflict, errors.New("user already exists"))
// In the handler — no status code knowledge needed
mux.POSTE("/users", func(w http.ResponseWriter, r *http.Request) error {
user, err := userService.Create(payload)
if err != nil {
return err // ErrUserExists passes through to ErrorHandler with 409
}
return muxmaster.JSON(w, http.StatusCreated, user)
})
Distinguish client errors from server errors in the error handler
mux.ErrorHandler = func(w http.ResponseWriter, r *http.Request, err error) {
var he muxmaster.HTTPError
if errors.As(err, &he) {
if he.StatusCode() >= 500 {
log.Printf("server error: %v", err) // log server errors
}
muxmaster.JSON(w, he.StatusCode(), map[string]string{"error": err.Error()})
return
}
log.Printf("unexpected error: %v", err) // always log unexpected errors
muxmaster.JSON(w, http.StatusInternalServerError, map[string]string{
"error": "internal server error",
})
}
Use errors.As to unwrap chains
muxmaster.Error wraps the original error, so you can unwrap the chain:
base := errors.New("record not found")
he := muxmaster.Error(http.StatusNotFound, base)
errors.Is(he, base) // true — unwraps through the HTTPError wrapper
See Also
- Response Helpers — JSON, XML, Text helpers
- Middleware —
RecovererWithLoggermiddleware - Cookbook — error handling patterns for production APIs
Common questions
How do I return an error from a MuxMaster handler?
Register a HandlerFuncE, a handler with the signature func(http.ResponseWriter, *http.Request) error, with GETE, POSTE, QUERYE, or another …E helper, or with HandleE.
A returned non-nil error is passed to Mux.ErrorHandler. muxmaster.Error(code, err) wraps an error with an HTTP status code.
What does MuxMaster send when a handler returns an error and no ErrorHandler is set?
MuxMaster sends 500 Internal Server Error with a plain-text body for every returned error when ErrorHandler is nil, even if the error is an HTTPError with another status code.
Set mux.ErrorHandler and use errors.As(err, &he) with a muxmaster.HTTPError to respond with the status code the error carries.
Does MuxMaster recover panics in handlers?
MuxMaster recovers panics only when you configure it to, with the RecovererWithLogger middleware or the Mux.PanicHandler field.
Register RecovererWithLogger with Pre to cover every request, including HandleFast routes. Without recovery, net/http recovers the panic itself and closes the connection.
Upstream source
This page mirrors docs/error-handling.md at the v1.3.0 tag. The behaviour it describes is implemented in handler.go, mux.go, response.go.