---
title: "Handling Errors"
description: "Hono provides a robust way to manage application errors, allowing you to catch failures and throw specific HTTP exceptions when issues arise."
last_updated: "2026-07-02T09:15:05.365018+00:00"
canonical_url: "https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/guide/troubleshooting/handling-errors"
---

Hono provides a robust way to manage application errors, allowing you to catch failures and throw specific HTTP exceptions when issues arise.

## Error Handling Overview

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.

## Using HTTP Exceptions

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.

```typescript
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!')
})
```

### HTTPException Options

| 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. |

## Error Lifecycle

The following diagram illustrates how Hono manages errors within the request lifecycle:

```mermaid
graph TD
    A[User Request] --> B{Route Handler}
    B -->|Success| C[Return Response]
    B -->|Error Thrown| D{Is it an HTTPException?}
    D -->|Yes| E[Create Response from Exception]
    D -->|No| F[Return 500 Internal Server Error]
    E --> G[Return Response]
    F --> G
```

> [!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.

## Related

- [Context API](https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/guide/core-concepts/context-api)


## Sitemap

See the full [sitemap](https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/llms.txt) for all pages in this wiki.