Getting Started
Core Concepts
Built-In Middleware
Advanced Features
Troubleshooting
Hono provides a robust way to manage application errors, allowing you to catch failures and throw specific HTTP exceptions when issues arise.
By default, Hono handles errors by logging them to the console and returning a 500 Internal Server Error response. You can use the built-in HTTPException to interrupt the request flow with specific status codes, custom messages, or custom response objects.
For expected failures, such as authentication errors or missing parameters, you should use the HTTPException class. When you throw an HTTPException, Hono automatically catches it and converts it into a proper Response object based on the status code provided.
import { Hono } from 'hono'
import { HTTPException } from 'hono/http-exception'
const app = new Hono()
app.get('/admin', async (c) => {
const isAuthorized = false
if (!isAuthorized) {
throw new HTTPException(401, { message: 'Unauthorized access' })
}
return c.text('Welcome!')
})| Option | Type | Description |
| message | string | The error message returned in the response. |
| res | Response | A custom Response object to return. |
| cause | unknown | The original error that caused this exception. |
The following diagram illustrates how Hono manages errors within the request lifecycle:
Tip
Always prefer HTTPException for flow control in your business logic. It clearly communicates intent and status to the client while keeping your route handlers clean.
Warning
If you do not call await next() in your middleware, or if you return a response without finalizing the context, Hono may throw a "Context is not finalized" error. Always ensure your handlers properly return a value or finalize the response.