whoops

go-whoops

Beautiful, interactive error pages for Go web applications. Inspired by PHP's Whoops.

Features

• Pretty error page with stack traces and inline source code
• Stacked handler system (LIFO) — combine HTML, JSON, plain text, and custom handlers
• Framework-agnostic core with zero external dependencies (stdlib only)
• Editor integration — click file paths to open in VSCode, GoLand, Cursor, Sublime, Vim, Emacs, and more
• Error chain visualization — see how errors propagate through layers
• Sensitive data scrubbing — auto-masks passwords, tokens, keys in headers, env vars, and query params
• Custom data panels — add your own tabs (session, user, feature flags, etc.)
• Content negotiation — serves HTML to browsers, JSON to API clients
• Dark/light theme toggle
• Search & keyboard navigation in stack frames
• Copy-to-clipboard for stack traces and source code
• Build info panel — Go version, module info, goroutine count
• Framework middleware as separate installable modules (Gin, Echo, Chi, Fiber)
• Logger integrations as separate installable modules (Zap, Zerolog, slog)

Quick Start

go get github.com/RezaKargar/go-whoops

net/http (built-in, zero extra deps)

package main

import (
    "net/http"
    "github.com/RezaKargar/go-whoops"
)

func main() {
    w := whoops.New()
    w.PushHandler(whoops.NewPrettyPageHandler(
        whoops.WithEditor(whoops.EditorVSCode),
    ))

    mux := http.NewServeMux()
    mux.HandleFunc("/", func(rw http.ResponseWriter, r *http.Request) {
        panic("something went wrong!")
    })

    http.ListenAndServe(":8080", w.HTTPMiddleware(mux))
}

Gin

go get github.com/RezaKargar/go-whoops/middleware/gin

import (
    "github.com/RezaKargar/go-whoops"
    whoopsgin "github.com/RezaKargar/go-whoops/middleware/gin"
)

w := whoops.New()
w.PushHandler(whoops.NewPrettyPageHandler())

router := gin.New()
router.Use(whoopsgin.Middleware(w, nil)) // nil = always render

Echo

go get github.com/RezaKargar/go-whoops/middleware/echo

import whoopsecho "github.com/RezaKargar/go-whoops/middleware/echo"

e := echo.New()
e.Use(whoopsecho.Middleware(w, nil))

Chi

go get github.com/RezaKargar/go-whoops/middleware/chi

import whoopschi "github.com/RezaKargar/go-whoops/middleware/chi"

r := chi.NewRouter()
r.Use(whoopschi.Middleware(w))

Fiber

go get github.com/RezaKargar/go-whoops/middleware/fiber

import whoopsfiber "github.com/RezaKargar/go-whoops/middleware/fiber"

app := fiber.New()
app.Use(whoopsfiber.New(w))

Handler Stack

Handlers are processed in LIFO order (last pushed = first to handle). Each handler returns an action:

w := whoops.New()

// First pushed: fallback JSON for API clients
w.PushHandler(whoops.NewJsonHandler(true))

// Second pushed: pretty HTML page for browsers (runs first due to LIFO)
w.PushHandler(whoops.NewPrettyPageHandler())

Built-in Handlers

Custom Error Types

go-whoops works with any error type. For rich error display, implement optional interfaces:

// Provide pre-captured stack trace
type StackProvider interface {
    StackPCs() []uintptr
}

// Provide error category
type KindProvider interface {
    ErrorKind() string
}

// Provide operation chain
type OperationProvider interface {
    Operation() string
}

// Provide metadata
type MetaProvider interface {
    ErrorMeta() map[string]any
}

// Provide HTTP status code
type StatusCodeProvider interface {
    StatusCode() int
}

See _examples/custom-unwrapper/ for a complete example.

Custom Data Panels

Add custom tabs to the error page:

type SessionProvider struct{}

func (p SessionProvider) Name() string { return "Session" }
func (p SessionProvider) Data(err error, r *http.Request) map[string]string {
    return map[string]string{
        "user_id": "123",
        "role":    "admin",
    }
}

w.PushDataProvider(SessionProvider{})

Logger Integrations

go get github.com/RezaKargar/go-whoops/integration/zap
go get github.com/RezaKargar/go-whoops/integration/zerolog
go get github.com/RezaKargar/go-whoops/integration/slog  # stdlib only

import whoopszap "github.com/RezaKargar/go-whoops/integration/zap"

logger, _ := zap.NewDevelopment()
w := whoops.New(whoops.WithLogger(whoopszap.New(logger)))

Editor Integration

Click file paths in the error page to open them directly in your editor:

whoops.NewPrettyPageHandler(
    whoops.WithEditor(whoops.EditorVSCode),   // or EditorGoLand, EditorCursor, etc.
)

Supported editors: VSCode, GoLand, Cursor, Zed, Sublime Text, Atom, Vim, Emacs, PhpStorm, IntelliJ IDEA.

Configuration

w := whoops.New(
    whoops.WithUnwrapper(myCustomUnwrapper{}),           // custom error type support
    whoops.WithScrubber(whoops.NewScrubber(myPatterns)),  // custom sensitive patterns
    whoops.WithLogger(myLogger),                          // error logging
    whoops.WithHandler(whoops.NewPrettyPageHandler()),     // add handler at construction
    whoops.WithDataProvider(myProvider),                   // add data panel
)

Architecture

See ARCHITECTURE.md for detailed design documentation.

Examples

Run the examples:

# Basic net/http example
go run ./_examples/basic/main.go

# Custom handler stack
go run ./_examples/custom-handler/main.go

# Custom error type with provider interfaces
go run ./_examples/custom-unwrapper/main.go

Then visit http://localhost:8080/error in your browser.

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License. See LICENSE for details.