mirror of https://github.com/gofiber/fiber.git
130 lines
4.1 KiB
Markdown
130 lines
4.1 KiB
Markdown
---
|
||
id: error-handling
|
||
title: 🐛 Error Handling
|
||
description: >-
|
||
Fiber supports centralized error handling by returning an error to the handler
|
||
which allows you to log errors to external services or send a customized HTTP
|
||
response to the client.
|
||
sidebar_position: 4
|
||
---
|
||
|
||
import Tabs from '@theme/Tabs';
|
||
import TabItem from '@theme/TabItem';
|
||
|
||
## Catching Errors
|
||
|
||
It’s essential to ensure that Fiber catches all errors that occur while running route handlers and middleware. You must return them to the handler function, where Fiber will catch and process them.
|
||
|
||
<Tabs>
|
||
<TabItem value="example" label="Example">
|
||
|
||
```go
|
||
app.Get("/", func(c fiber.Ctx) error {
|
||
// Pass error to Fiber
|
||
return c.SendFile("file-does-not-exist")
|
||
})
|
||
```
|
||
|
||
</TabItem>
|
||
</Tabs>
|
||
|
||
Fiber does not handle [panics](https://go.dev/blog/defer-panic-and-recover) by default. To recover from a panic thrown by any handler in the stack, you need to include the `Recover` middleware below:
|
||
|
||
```go title="Example"
|
||
package main
|
||
|
||
import (
|
||
"log"
|
||
|
||
"github.com/gofiber/fiber/v3"
|
||
"github.com/gofiber/fiber/v3/middleware/recover"
|
||
)
|
||
|
||
func main() {
|
||
app := fiber.New()
|
||
|
||
app.Use(recover.New())
|
||
|
||
app.Get("/", func(c fiber.Ctx) error {
|
||
panic("This panic is caught by fiber")
|
||
})
|
||
|
||
log.Fatal(app.Listen(":3000"))
|
||
}
|
||
```
|
||
|
||
You could use Fiber's custom error struct to pass an additional `status code` using `fiber.NewError()`. It's optional to pass a message; if this is left empty, it will default to the status code message \(`404` equals `Not Found`\).
|
||
|
||
```go title="Example"
|
||
app.Get("/", func(c fiber.Ctx) error {
|
||
// 503 Service Unavailable
|
||
return fiber.ErrServiceUnavailable
|
||
|
||
// 503 On vacation!
|
||
return fiber.NewError(fiber.StatusServiceUnavailable, "On vacation!")
|
||
})
|
||
```
|
||
|
||
## Default Error Handler
|
||
|
||
Fiber provides an error handler by default. For a standard error, the response is sent as **500 Internal Server Error**. If the error is of type [fiber.Error](https://godoc.org/github.com/gofiber/fiber#Error), the response is sent with the provided status code and message.
|
||
|
||
```go title="Example"
|
||
// Default error handler
|
||
var DefaultErrorHandler = func(c fiber.Ctx, err error) error {
|
||
// Status code defaults to 500
|
||
code := fiber.StatusInternalServerError
|
||
|
||
// Retrieve the custom status code if it's a *fiber.Error
|
||
var e *fiber.Error
|
||
if errors.As(err, &e) {
|
||
code = e.Code
|
||
}
|
||
|
||
// Set Content-Type: text/plain; charset=utf-8
|
||
c.Set(fiber.HeaderContentType, fiber.MIMETextPlainCharsetUTF8)
|
||
|
||
// Return status code with error message
|
||
return c.Status(code).SendString(err.Error())
|
||
}
|
||
```
|
||
|
||
## Custom Error Handler
|
||
|
||
A custom error handler can be set using a [Config](../api/fiber.md#errorhandler) when initializing a [Fiber instance](../api/fiber.md#new).
|
||
|
||
In most cases, the default error handler should be sufficient. However, a custom error handler can come in handy if you want to capture different types of errors and take action accordingly e.g., send a notification email or log an error to the centralized system. You can also send customized responses to the client e.g., error page or just a JSON response.
|
||
|
||
The following example shows how to display error pages for different types of errors.
|
||
|
||
```go title="Example"
|
||
// Create a new fiber instance with custom config
|
||
app := fiber.New(fiber.Config{
|
||
// Override default error handler
|
||
ErrorHandler: func(ctx fiber.Ctx, err error) error {
|
||
// Status code defaults to 500
|
||
code := fiber.StatusInternalServerError
|
||
|
||
// Retrieve the custom status code if it's a *fiber.Error
|
||
var e *fiber.Error
|
||
if errors.As(err, &e) {
|
||
code = e.Code
|
||
}
|
||
|
||
// Send custom error page
|
||
err = ctx.Status(code).SendFile(fmt.Sprintf("./%d.html", code))
|
||
if err != nil {
|
||
// In case the SendFile fails
|
||
return ctx.Status(fiber.StatusInternalServerError).SendString("Internal Server Error")
|
||
}
|
||
|
||
// Return from handler
|
||
return nil
|
||
},
|
||
})
|
||
|
||
// ...
|
||
```
|
||
|
||
> Special thanks to the [Echo](https://echo.labstack.com/) & [Express](https://expressjs.com/) framework for inspiration regarding error handling.
|