Honeybadger Developer Blog

A comprehensive guide to Fly.io logging

2026-08-13T07:00:00+00:00

Deployment is not the end of shipping your application. From time to time, you will get errors that you will need to attend to. Without a good method of catching errors or logs in general, you could end up with uncaught issues that might cost you valuable customers in the process.

In this article, you will learn how to catch logs for an application deployed on Fly.io. You will learn how Fly.io logging works, then learn ways to handle logs natively on the platform. Finally, we will see a better way of logging with Honeybadger.

How does Fly.io logging work?

Fly.io runs deployed apps inside a lightweight VM booted from an unpacked image. In each container where the application is running, a process (init) is activated to run and monitor your app. This init program, along with others, collects the application's output from stdout or stderr and redirects it to the host machine.

It is not enough to just collect logs; we still need a way to handle and manage any potential errors or logs. In the host machine, Fly.io uses a socket to send the logs to Vector. The logs are then sent into Fly's internal NATS cluster, where Clients can subscribe to specific topics. In Fly log shipper, Vector acts as a NATS client, reads the logs, and ships them to a Vector Sink (e.g., Honeybadger).

Basic way to access logs on Fly.io

Fly.io makes it easy to access application logs. Since applications running on Fly.io write output to standard output (stdout) and standard error (stderr), Fly.io automatically collects and streams those logs for you.

In this section, you will deploy a sample FastAPI project to Fly.io. The application is intentionally built to generate application logs for the learning process.

Building a FastAPI application that generates logs

To demonstrate logging, we will build a simple API with endpoints that generate different types of log messages.

Create a project directory and move into it:

mkdir flyio-logging-demo
cd flyio-logging-demo

Create a virtual environment and activate it:

python -m venv venv
source venv/bin/activate

Install FastAPI and Uvicorn:

pip install fastapi uvicorn

Create a file named main.py and add the following code:

import logging
from fastapi import FastAPI

app = FastAPI()

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(message)s"
)

logger = logging.getLogger(__name__)

@app.get("/")
def home():
    logger.info("User created")
    return {"message": "Hello from Fly.io"}

@app.get("/login")
def login():
    logger.warning("Rate limit approaching")
    return {"message": "Login request received"}

@app.get("/error")
def error():
    logger.error("Database connection failed")
    return {"message": "Error logged"}

The application contains three endpoints:

/ generates an informational log
/login generates a warning log
/error generates an error log

Fly.io automatically captures the following logs:

print("Application started")
logger.info("User created")
logger.warning("Rate limit approaching")
logger.error("Database connection failed")

As long as your application writes output to standard output or standard error, Fly.io will collect and surface those logs.

Now you can run your app with the following command:

uvicorn main:app --reload

Open another terminal and send requests to generate logs:

curl http://localhost:8000/ -w "\n" && curl http://localhost:8000/login -w "\n" && curl http://localhost:8000/error -w "\n"

Your terminal should display output similar to:

{"message":"Hello from Fly.io"}
{"message":"Login request received"}
{"message":"Error logged"}

Now that the application is generating logs, we can deploy it to Fly.io.

Containerizing the application

Here we will put the application in a Docker container for easy deployment. Start by creating a file named requirements.txt and adding the following to it:

fastapi
uvicorn

Next, create a file named Dockerfile and copy and paste this into it:

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .

RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

The Dockerfile installs the application dependencies and starts the FastAPI server.

Creating a Fly.io application

Assuming you already have an account on Fly.io, install Fly.io CLI and log in to Fly.io using the CLI:

fly auth login

Initialize a new Fly application:

fly launch

Fly.io will ask a few questions about your application configuration and then generate a fly.toml file. You can review the generated configuration and accept the defaults for this tutorial.

Now you can deploy your application with the following command:

fly deploy

Fly.io will build the container image and start a Machine running your FastAPI application. After deployment completes, open the application:

fly open

You should see the JSON response:

{
  "message": "Hello from Fly.io"
}

Now generate some logs from the deployed application by sending requests to each endpoint or opening them in the browser.

Each request produces log output that Fly.io collects automatically. You can tail live logs with the fly logs command:

fly logs

You should see output similar to this:

2026-05-31T17:14:42Z app[d89492dc3e5208] cdg [info]2026-05-31 17:14:42,377 INFO User created
2026-05-31T17:14:42Z app[d89492dc3e5208] cdg [info]INFO:     172.16.45.10:59882 - "GET / HTTP/1.1" 200 OK
2026-05-31T17:14:42Z app[d89492dc3e5208] cdg [info]INFO:     172.16.45.10:59894 - "GET /favicon.ico HTTP/1.1" 404 Not Found
2026-05-31T17:16:57Z app[d89492dc3e5208] cdg [info]2026-05-31 17:16:57,535 ERROR Database connection failed
2026-05-31T17:16:57Z app[d89492dc3e5208] cdg [info]INFO:     172.16.45.10:52308 - "GET /error HTTP/1.1" 200 OK
2026-05-31T17:17:23Z app[d89492dc3e5208] cdg [info]2026-05-31 17:17:23,565 WARNING Rate limit approaching
2026-05-31T17:17:23Z app[d89492dc3e5208] cdg [info]INFO:     172.16.45.10:39662 - "GET /login HTTP/1.1" 200 OK

These logs are streamed in real time. To test this, leave the command running and make additional requests to the API. New log entries will appear immediately.

While this is one way to keep an eye on your logs, this method is not really efficient when monitoring application issues during deployment because it requires you to watch your logs at all times. But it can sometimes be useful for debugging.

If you work with multiple Fly applications, specify the application name:

fly logs -a my-fastapi-app

This ensures you only receive logs from the application you are interested in.

Applications can run on multiple machines. You can see a list of your Machines:

fly machine list

You can inspect a Machine using the Machine ID:

fly machine status d89492dc3e5208

This is useful when troubleshooting issues affecting only a single Machine instance.

Viewing logs from the Fly.io dashboard

Fly.io also provides live tail logs through its web dashboard.

Open your application in the Fly.io dashboard and navigate to the Logs section. Here you will see a view of your application's log stream, which can be convenient when you are away from your terminal or reviewing recent activity.

For simple debugging tasks, the fly logs command is the quickest way to inspect application activity. As your applications grow, log management becomes an important part of understanding application behavior and monitoring the health of your services, and tools like Honeybadger Insights help manage them effectively.

Shipping Fly.io logs to Honeybadger Insights

As mentioned earlier, Vector acts as a NATS client, and this is the basis of the Fly log shipper. Vector grabs the log and sends it to a location of your choosing. In this section, you will learn how to ship your Fly.io logs to Honeybadger Insights using the Fly log shipper.

To get started, we first need to create a new app for Fly log shipper. Run the following command to create a new directory and navigate into that directory:

mkdir logshipper
cd logshipper

Now you can create the log shipper app in the directory you just created:

fly launch --no-deploy --image ghcr.io/superfly/fly-log-shipper:latest

We are adding the --no-deploy so it just creates and configures the app and does not deploy it, since we need to add a few configurations before deployment. --image specifies the prebuilt image to be configured and later deployed.

Now we will set some secrets. Create a new project on Honeybadger and get the API key from that project. Setting HONEYBADGER_API_KEY enables the shipping of logs to your Honeybadger project.

fly secrets set ORG=personal # The org you chose when running "fly launch"
fly secrets set ACCESS_TOKEN=$(fly auth token) # gets and sets Fly token 
fly secrets set HONEYBADGER_API_KEY=PROJECT_API_KEY

Keeping your Fly tokens in secrets rather than hard-coding them helps protect access to your Fly.io infrastructure.

Edit the generated fly.toml file, replacing the entire [http_service] section with this:

[[services]]
  http_checks = []
  internal_port = 8686

You can now deploy the logger application:

fly deploy

Once that's done, you should see logs from your apps flowing into Insights. When you send requests to your deployed app, you will see the activity logged on to Honeybadger Insights.

On Honeybadger, you can run many queries on these logs, including searches like this:

fields @ts, @preview
| filter fly.app.name::str == "fly-honeybadger"
| sort @ts

In this query, we’ve piped the initial results (fields @ts, @preview) through filter, which accepts a variety of conditions. Here we have specified the data type of the fly.app.name field as str and compare to the string provided ("fly-honeybadger").

Basically, this is going through your logs and selecting the apps on Fly.io with the name “fly-honeybadger”. This can be helpful when you have multiple applications deployed on Fly.io.

More on Honeybadger Insights

In this article, you saw how Fly.io captures everything your application writes to stdout and stderr, and how Fly's internal architecture (Vector → NATS → log shipper) makes it straightforward to route logs to external destinations. We then saw how to use Insights as a more well-rounded solution for logging.

We only went through a surface level of what Insights is capable of when it comes to Fly.io logging, establishing a foundation for the deeper view into data analytics that Honeybadger enables. Having all that data available in one place reduces the time it takes to find answers, enabling you to easily:

Query and filter Fly.io logs using Honeybadger's powerful search language.
Correlate logs with application errors or other application metrics.
Monitor application behavior across multiple Fly.io deployments.
Analyze your logs.

If you are already using Fly.io in production, this article demonstrated one of the simplest ways to move from basic log viewing to a complete observability workflow with no additional code needed.

Now that you know everything you need to about Fly.io logging, sign up for a free Honeybadger account and start shipping your Fly.io logs today.

August 2026 product update: hosted MCP and more

2026-08-12T07:00:00+00:00

Your MCP client doesn’t need your whole API key just to look up an error anymore.

Honeybadger's hosted MCP server now supports OAuth. You can approve it through your browser, scope your permissions, revoke your permissions, and rest easy knowing that our tokens auto-refresh and don’t sit around in a config.

Keep reading to see how it works and get a quick recap of everything else that shipped this cycle.

MCP gets OAuth, and self-hosting gets more flexible

Until now, connecting an AI agent to Honeybadger's MCP server meant handing it a personal API token, giving it full account access and no way to reduce its scope. If you wanted to give Claude or Cursor read-only access to investigate errors, you were stuck granting it everything.

The new hosted server fixes that. Add https://mcp.honeybadger.io/mcp to your client and approve the connection in your browser — no local install or token to manage.

The first time a client connects, you pick an account and choose read-only or read-write access. Behind the scenes, Honeybadger issues short-lived tokens that refresh automatically, so there's no long-lived secret sitting in a config file. You can review or revoke any connected app anytime from User Settings → API Access (or, for admins, from any team member's account under Account Settings → API Access).

Getting started:

Claude Code:

claude mcp add --transport http honeybadger "https://mcp.honeybadger.io/mcp"

Cursor, Windsurf, and Claude Desktop use a JSON config:

json

{
  "mcpServers": {
    "honeybadger": {
      "url": "https://mcp.honeybadger.io/mcp"
    }
  }
}

VS Code has its own CLI equivalent:

code --add-mcp '{"name":"honeybadger","type":"http","url":"https://mcp.honeybadger.io/mcp"}'

EU accounts should use https://eu-mcp.honeybadger.io/mcp instead. Each endpoint only accepts accounts from its own region.

EU support is also here

If you want to use the self-hosted MCP with the EU stack, you can set HONEYBADGER_API_URL to https://eu-app.honeybadger.io in the env block (and add a matching -e HONEYBADGER_API_URL entry to args for Docker, so the variable actually gets passed through), then authenticate with a personal auth token from your EU user settings. Keep in mind that a US token won't work against the EU region, and vice versa.

What to do with your MCP

Once connected, your agent can list and manage projects, search and filter errors, look at stack traces and affected users, run BadgerQL queries against Insights, and manage dashboards and alarms. The server also handles your agent reference material from BadgerQL and error search syntax automatically, so you don't need to paste documentation into your prompts.

Full setup instructions, including client-specific configuration and building from source, are in the MCP documentation.

Also shipped this month

Natural language search. Error search and BadgerQL can answer almost any question about your errors and events, but only if you remember the syntax. Now you can describe what you want instead. Just click the lightbulb next to the search box, type something like "unresolved production errors from the last 24 hours that have comments," and Honeybadger writes the query for you, editable and ready to run.

Anomaly detection. Some of the worst incidents don't show up as one new error; they show up as a flood. Honeybadger now learns each project's normal error volume and alerts you when it spikes above that baseline — no thresholds to configure. Available on Business and Enterprise plans.

Oban-py support. Honeybadger now integrates with the Python port of Oban’s background job library. Unhandled worker exceptions are reported automatically, per-job telemetry flows into Insights, and request context carries through to the jobs it enqueues.

That's everything from July. As always, the full history is on the changelog. If you're interested in trying out any of these features, a Honeybadger account starts out as free for a single user.

Comprehensive guide to working with Python markdown

2023-11-27T08:00:00+00:00

If you use the Internet, you have surely come across the term Markdown. Markdown is a lightweight markup language that makes it very easy to write formatted content. It was created by John Gruber and Aaron Swartz in 2004. It uses very easy-to-remember syntax and is therefore used by many bloggers and content writers around the world. Even this blog that you are reading is written and formatted using Markdown.

Markdown is one of the most widely used formats for storing formatted data. It easily integrates with Web technologies, as it can be converted to HTML or vice versa using Markdown compilers. It allows you to write HTML entities, such as headings, lists, images, links, tables, and more without much effort or code. It is used in blogs, content management systems, Wikis, documentation, and many more places.

In this article, you'll learn how to work with Python markdown application using different Python packages, including markdown, front matter, and markdownify.

Prerequisites

To follow along with this tutorial, you’ll need the following:

Python v3.x
Basic understanding of HTML and Markdown

Setting Up a Project

Before proceeding with the project, you’ll need to set up a project directory to work in.

So, first, open up your terminal, navigate to a path of your choice, and create a project directory (python-markdown) by running the following commands in the terminal:

mkdir python-markdown
cd python-markdown

Finally, create and activate the virtual environment (venv) for your Python project by running the following commands:

python3 -m venv
source venv/bin/activate

That’s it. The project setup is complete.

By the way, if you are building Python web apps, we send practical Python, Django, and software engineering articles—no hype, just useful stuff. Sign up for our newsletter

Converting Markdown to HTML in Python

One of the most common operations related to Markdown is converting it to HTML. By doing so, you can write your content in Markdown and then compile it to HTML, which you can then deploy to a CDN or server.

First, install the python-markdown package by running the following command in the terminal:

pip install markdown

Next, at your project’s root directory, create a main.py file and add the following code to it:

# 1
import markdown

markdown_string = '# Hello World'

# 2
html_string = markdown.markdown(markdown_string)
print(html_string)

In the above code, you are doing the following:

Importing the markdown module.
Converting the markdown (markdown_string) to HTML (html_string) using the markdown method from the markdown package.

Finally, save your code and run the main.py file by running the following command in the terminal:

python main.py

Once the code execution is complete, you’ll get the HTML output as follows:

You can try a more complex Markdown string like the one in the code below and use it to create HTML:

markdown_string = '''
# Hello World

This is a **great** tutorial about using Markdown in [Python](https://python.org).
'''

In this example, you make use of headings, bold text, and links in Markdown.

Converting a Markdown File to HTML in Python

Most of the time, you’ll be working with Markdown files rather than Markdown strings. Therefore, it makes sense to learn how to convert a Markdown file to an HTML file.

To do so, first, create a sample.md file and add the following code to it:

# Hello World

This is a **Markdown** file.

Next, replace the existing code in the main.py file with the following:

import markdown

# 1
with open('sample.md', 'r') as f:
    markdown_string = f.read()

# 2
html_string = markdown.markdown(markdown_string)

# 3
with open('sample.html', 'w') as f:
    f.write(html_string)

In the above code, you are doing the following:

Reading the sample.md and storing its content in the markdown_string variable.
Converting the markdown (markdown_string) to HTML (html_string) using the markdown method from the markdown package.
Creating a sample.html file and writing the HTML (html_string) to it.

Finally, save your code and run the main.py file by running the following command in the terminal:

python main.py

Once the code execution is complete, you’ll see a sample.html file in your project’s root directory:

Converting HTML to Markdown in Python

Sometimes, a situation arises where you might want to convert HTML to Markdown. For this purpose, you can use the markdownify package in Python.

First, install the package by running the following command in the terminal:

pip install markdownify

Next, replace the existing code in the main.py file with the following:

# 1
import markdownify

html_string = '''
<h1>Hello World</h1>
<p>This is a great tutorial about using Markdown in Python.</p>
'''

# 2
markdown_string = markdownify.markdownify(html_string)
print(markdown_string)

In the above code, you are doing the following:

Importing the markdownify module.
Converting the HTML (html_string) to Markdown (markdown_string) using the markdownify method from the markdownify package.

Finally, save your code and run the main.py file by running the following command in the terminal:

python main.py

Once the code execution is complete, you’ll get the Markdown output:

If you see the output above, you’ll see the headings (<h1>) created with the "underlining" with equal signs (=) instead of starting with hashtags (#). This is because Markdown comes with two styles of headers: Setext and atx, and by default, the Markdown parser uses Setext-style headers. You configure markdownify to use ATX-style headers by passing the heading_style='ATX' parameter to the markdownify method.

Markdownify also supports a number of options, including HTML tag stripping, HTML tag conversion, Markdown heading styles, and more.

Converting an HTML File to Markdown in Python

Previously, we converted a Markdown file to an HTML file. However, sometimes, you might need to convert an HTML file to a Markdown file.

To do so, first, create a sample.html file and add the following code to it:

<!DOCTYPE html>
<html lang="en">
<body>
    <h1>Hello World</h1>
    <p>This is a <strong>HTML</strong> file.</p>
    <a href="https://honeybadger.io/">Visit Honeybadger</a>
</body>
</html>

Next, replace the existing code in the main.py file with the following:

import markdownify

# 1
with open('sample.html', 'r') as f:
    html_string = f.read()

# 2
markdown_string = markdownify.markdownify(html_string, heading_style='ATX')

# 3
with open('sample.md', 'w') as f:
    f.write(markdown_string)

In the above code, you’re doing the following:

Reading the sample.html and storing its content in the html_string variable.
Converting the HTML (html_string) to Markdown (markdown_string) using the markdownify method from the markdownify package.
Creating a sample.md file and writing the Markdown (markdown_string) to it.

Finally, save your code and run the main.py file by running the following command in the terminal:

python main.py

Once the code execution is complete, you’ll see a sample.md file in your project’s root directory as follows:

Using Front Matter for Python markdown

In the world of markdown, there are often some variables or metadata associated with a Markdown file. This is known as front matter. Front matter data variables are a great way to store extra information about a Markdown file. For example, a blog’s markdown files can have front matter variables like Title, Author, Image, Published At, and more.

You can specify front matter at the beginning of a Markdown file by placing the YAML data variables between triple-dashed lines. For example,

---
title: Hello World
Author: John Doe
Published: 2020-01-20
---

In Python, you can parse Markdown front matter with the python-front matter package.

To see this package in action, first, install the package by running the following command in the terminal:

pip install python-frontmatter

Next, add the following front matter to the sample.md file:

---
title: Hello World
date: 2022-01-20
---

Next, replace the existing code in the main.py file with the following:

# 1
import frontmatter

# 2
data = frontmatter.load('sample.md')

# 3
print(data.keys())
print(data['title'])
print(data['date'])

In the above code, you are doing the following:

Importing the frontmatter module.
Reading the sample.md file using the load method from the frontmatter package and storing the result in the data variable.
Accessing the front matter variables with the help of data.keys(). Since data is a dictionary, you can also access the individual keys (data['title'] or data['date']).

Finally, save your code and run the main.py file by running the following command in the terminal:

python main.py

Once the code execution is complete, you’ll get the output of the front matter variables as follows:

Updating Markdown Front Matter in Python

Sometimes, a situation arises where you might want to convert HTML to Markdown. For this purpose, you can use the Python’s markdownify package.

You can also update the existing front matter data variables or add new ones using the front matter package.

To do so, first, replace the existing code in the main.py file with the following:

import frontmatter

# 1
data = frontmatter.load('sample.md')

# 2
data['author'] = 'John Doe'

# 3
data['title'] = 'Bye World'

# 4
updated_data = frontmatter.dumps(data)

# 5
with open('sample.md', 'w') as f:
    f.write(updated_data)

In the above code, you are doing the following:

Reading (frontmater.load()) the sample.md file.
Adding a new key (author) to the front matter data variable and assigning it a value (John Doe).
Updating the existing key (title) and assigning it a new value (Bye World).
Serializing (frontmatter.dumps()) the data variable to a string and storing the result in the updated_data variable.
Updating the sample.md file by writing the updated Markdown (updated_data) to it.

Finally, save your code and run the main.py file by running the following command in the terminal:

python main.py

Once the code execution is complete, check the sample.md file for the updated front matter data, as follows:

Using Python Markdown Extensions

The python-markdown package also supports extensions that allow you to modify and/or extend the default behavior of the Markdown parser. For example, to generate a table of contents (TOC), you can use the toc extension. There are other extensions, as well, which you can make use of based on your requirements.

To create a TOC for your Markdown content, first, replace the existing code in the main.py file with the following:

import markdown

# 1
markdown_string = '''
[TOC]

# Hello World

This is a **great** tutorial about using Markdown in [Python](https://python.org).

# Bye World
'''

# 2
html_string = markdown.markdown(markdown_string, extensions=['toc'])
print(html_string)

In the above code, you are doing the following:

Specifying the [TOC] string in your Markdown (markdown_string) where you want to add the table of contents.
Adding the extensions parameter to the markdown method from the markdown package and specifying the extensions (['toc']) you want to use.

Finally, save your code and run the main.py file by running the following command in the terminal:

python main.py

Once the code execution is complete, you’ll get the HTML output with the Table of Contents as a list:

where do you go from here?

Learning to work with Markdown can help you in lots of ways. Using this guide as the basis, you can automate many tasks, including maintaining and manipulating Markdown files. For example, you can write a script that creates an index for all of your Python markdown files in your blog or organize your markdown files into different directories based on the front matter data variables, such as tags/categories.

Honeybadger, which is a cloud-based system for real-time monitoring, error tracking, and exception-catching, also uses Markdown to maintain our documentation. In case you are interested, we wrote a blog post in which we talk about how we built a documentation workflow in Rails.

Starlette vs FastAPI: what FastAPI actually adds

2026-07-20T07:00:00+00:00

FastAPI has become one of the most popular web frameworks among Python developers. It's so popular that it often overshadows the technologies it's built on. FastAPI is built on Starlette and Pydantic. Starlette handles the HTTP layer (routing, middleware, WebSockets, the ASGI plumbing) and Pydantic handles data validation. FastAPI is the layer on top that ties them together with type-driven parameter parsing, dependency injection, and automatic OpenAPI documentation.

That overshadowing is why the Starlette vs FastAPI choice is often framed as choosing between direct competitors, as if you have to pick sides. You don't. The real question is what FastAPI adds and when you might skip it. In this article, I'll walk through the parts of a FastAPI application that come straight from Starlette, the parts FastAPI adds on top, and a few cases where dropping down to raw Starlette is the better call.

What Starlette and FastAPI actually are

Starlette is a lightweight ASGI toolkit. ASGI is the asynchronous successor to WSGI, and it's the spec that lets Python web servers like Uvicorn and Hypercorn talk to async applications. Starlette consists of a routing system, request and response objects, a middleware pipeline, WebSocket support, background tasks, sessions, a test client, and a small set of built-in middlewares for things like CORS and GZip. That's everything you need to build an async web service against the spec, small and unopinionated by design.

Pydantic is the other half of the foundation. It's a general-purpose data validation library: you declare a class with typed fields, and Pydantic handles parsing, validation, serialization, and JSON Schema generation for free. FastAPI happens to use it. So does anything else that needs typed data shapes.

FastAPI is a thin layer that hooks into Starlette and Pydantic through your function signatures; when you write def create_user(user: User), FastAPI sees the Pydantic model in the type hint and wires up Starlette's request body parsing to it. That one mechanism is the foundation of everything FastAPI does: parameter parsing, validation, and OpenAPI schema generation are all derivatives of reading your type hints. The docs and dependency injection are conveniences built on top.

The diagram above is the mental model worth keeping. Whenever you write a FastAPI app, you're really writing code that sits on FastAPI, which sits on Starlette and Pydantic, which talk to an ASGI server underneath.

Starlette vs FastAPI: core differences

The two frameworks make fundamentally different tradeoffs. Starlette gives you low-level HTTP building blocks: routing, middleware, and WebSockets, without prescribing structure. FastAPI adds a declarative layer on top: automatic validation, serialization, interactive docs, and dependency injection, all driven by standard Python type hints.

With Starlette, you wire up validation and injection yourself or skip them. With FastAPI, you declare what you need in the function signature and get validation and failure responses for free.

Both share the same async runtime. The difference is how much boilerplate you need to write.

Performance and async capabilities

FastAPI gets its async def support from Starlette; there's no separate event loop or async runtime. A FastAPI async def endpoint uses Starlette's ASGI integration the same way a raw Starlette endpoint does.

A Starlette async def endpoint looks like this:

from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.routing import Route

async def homepage(request):
    return JSONResponse({"hello": "world"})

app = Starlette(routes=[Route("/", homepage)])

A FastAPI async def endpoint looks like this:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def homepage():
    return {"hello": "world"}

Both run on the same ASGI app and event loop. The async I/O behavior is identical. FastAPI's decorator adds route registration, serialization, and OpenAPI schema generation. Starlette gives you the route and response object.

However, FastAPI handles sync functions differently. Declare a path operation with def instead of async def, and FastAPI runs it in a threadpool—so a slow call doesn't stall the event loop. Starlette does the same, but FastAPI extends this to dependencies too, which matters once you use its injection system.

The threadpool isn't infinite. Both frameworks use AnyIO, which by default caps the pool at 40 worker threads. A few slow sync handlers under load can saturate it, causing the threadpool to queue requests. Mixing def and async def without considering the thread pool is a common reason a FastAPI app feels fast in testing but slow under load. The fix is usually to push the slow work into a background worker, not to bump the threadpool limit.

Middleware: same stack, same tools

Middleware is one of the clearest examples of FastAPI sitting on Starlette without modification. The middleware pipeline, the base classes, and the bundled middlewares all come from Starlette. FastAPI just re-exports them.

A custom middleware in Starlette looks like this:

from starlette.middleware.base import BaseHTTPMiddleware

class TimingMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request, call_next):
        import time
        start = time.perf_counter()
        response = await call_next(request)
        response.headers["X-Process-Time"] = f"{time.perf_counter() - start:.4f}"
        return response

The same class drops straight into a FastAPI app:

from fastapi import FastAPI

app = FastAPI()
app.add_middleware(TimingMiddleware)

This works because FastAPI implements the ASGI spec through Starlette, so any ASGI middleware works in either framework. The built-in CORSMiddleware, GZipMiddleware, TrustedHostMiddleware, and SessionMiddleware you reach for in a FastAPI app all live in the starlette.middleware package.

Two Starlette quirks apply unchanged in FastAPI. First, middleware is registered in LIFO order, so the last add_middleware call runs first on the way in and last on the way out.

Second, BaseHTTPMiddleware doesn't propagate contextvars changes to the rest of the request. If you're doing distributed tracing or request-scoped logging, write a raw ASGI middleware instead.

For production, you need middleware that catches errors. A raw 500 doesn't tell you much. A thin wrapper is the cleanest place to capture the stack trace, URL, and request context before sending the response. Here's an example that reports unhandled errors to Honeybadger, which notifies your team immediately:

from starlette.middleware.base import BaseHTTPMiddleware
from honeybadger import honeybadger

class HoneybadgerMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request, call_next):
        try:
            return await call_next(request)
        except Exception as exc:
            honeybadger.notify(exc, context={
                "path": request.url.path,
                "method": request.method,
            })
            raise

app.add_middleware(HoneybadgerMiddleware)

Because the middleware contract is Starlette's, the same code works in both frameworks without modification. If you ever migrate a service from FastAPI to bare Starlette (or vice versa), the middleware remains unchanged.

If you're using the Honeybadger Python SDK, you don't need to write this yourself. The SDK ships with a built-in Starlette middleware that catches exceptions, attaches request context, and sends everything to Honeybadger.

WebSocket support

WebSockets are another part of FastAPI that's almost entirely Starlette underneath. The WebSocket object, the connection lifecycle (accept, receive_text, send_json, close), and the WebSocketDisconnect exception all come from starlette.websockets.

FastAPI re-exports them and adds the same dependency injection and parameter parsing it adds to HTTP routes.

A FastAPI WebSocket endpoint:

from fastapi import FastAPI, WebSocket, WebSocketDisconnect

app = FastAPI()

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    try:
        async for message in websocket.iter_text():
            await websocket.send_text(f"Echo: {message}")
    except WebSocketDisconnect:
        pass

Apart from the decorator, every line is Starlette code. The Starlette version uses WebSocketRoute instead.

What FastAPI adds is dependency injection: you can pull a database session, authenticated user, or query parameter into a WebSocket handler the same way you would in an HTTP route.

If your service is mostly WebSocket-driven and you don't need OpenAPI docs for HTTP routes, a Starlette application gets you the same capabilities with less to install.

Data validation and serialization

This is where the two frameworks feel different. Starlette doesn't know anything about Pydantic. You can absolutely use them together, but you do the wiring by hand. FastAPI's defining feature is that it handles the wiring for you, using your function signature and standard Python type hints.

Here's the same "create a user" endpoint written both ways. With Starlette and Pydantic, you're responsible for parsing the request data, calling Pydantic, and converting validation errors into the right failure response for incoming requests:

from pydantic import BaseModel, ValidationError
from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.routing import Route

class User(BaseModel):
    name: str
    email: str
    age: int

async def create_user(request):
    payload = await request.json()
    try:
        user = User(**payload)
    except ValidationError as exc:
        return JSONResponse({"errors": exc.errors()}, status_code=422)
    return JSONResponse(user.model_dump(), status_code=201)

app = Starlette(routes=[Route("/users", create_user, methods=["POST"])])

The FastAPI version is shorter because the framework infers all of the above from the type hint:

from fastapi import FastAPI
from pydantic import BaseModel

class User(BaseModel):
    name: str
    email: str
    age: int

app = FastAPI()

@app.post("/users", status_code=201)
async def create_user(user: User):
    return user

FastAPI sees the User parameter, parses the incoming JSON data, validates it against the Pydantic data model, returns a 422 response with structured error details if validation fails, and serializes the return value back to JSON.

It works in reverse, too. With a response_model, FastAPI validates and filters your return value before sending it, preventing database columns from leaking to API clients without requiring a custom serialization layer. Starlette leaves output filtering to you.

Both frameworks handle nested Pydantic models. The difference is who does the wiring.

That's "FastAPI built on Starlette and Pydantic" in practice. Starlette provides the HTTP objects, Pydantic provides validation, and FastAPI connects your function signature to both.

The cost is mostly conceptual: more magic between the request and your function. For most APIs, that's a good trade. When you need full control over request parsing, Starlette is cleaner.

Automatic documentation generation

For many teams, this is the one feature that settles it. Starlette doesn't generate API docs. You can wire up swagger-ui or apispec yourself, but nothing is built in.

FastAPI generates an OpenAPI 3.1 schema automatically from your path operations and Pydantic models, and serves two interactive doc UIs out of the box:

Swagger UI at /docs
ReDoc at /redoc

It helps to be clear about who does what. Pydantic generates a JSON Schema for each data model. FastAPI assembles those schemas into a full OpenAPI document per the OpenAPI standard, along with path info from your decorators (URLs, methods, status codes, tags), and serves the result via Swagger UI and ReDoc. Without Pydantic, FastAPI would have no schemas to embed. Without FastAPI, you'd have schemas but nothing tying them to URLs.

The schema includes parameter types, request and response data models, validation constraints, status codes, and any descriptions you add. There's no separate file to maintain and no annotations to keep in sync. Because the schema is derived from the same type hints that drive validation, it can't drift out of date with your endpoints.

For internal services, this turns the API itself into the docs. For public APIs, the OpenAPI schema can be used to generate client code, contract testing tools, and API gateways. Replicating this automatic documentation in a Starlette application is doable but noticeable work.

When to use Starlette directly

Most projects are well served by FastAPI. I'd reach for Starlette directly only where the FastAPI layer would mostly sit unused.

Webhook receivers and lightweight proxies. If your service does little more than accept a payload, validate a signature, and forward it somewhere, the OpenAPI schema and Pydantic-driven validation aren't earning their keep. A Starlette application with a couple of routes is smaller, starts faster, and has fewer moving parts.
WebSocket-heavy services. If your application is mostly WebSocket connections with little or no REST surface, FastAPI's HTTP-focused additions don't apply to most of your code. Starlette's WebSocket primitives are exactly what FastAPI uses anyway.
Custom request handling. If you need to stream a request body, parse a non-standard content type, or short-circuit before the body is fully read, FastAPI's parameter parsing can fight you. Starlette's lower-level request object gives you direct control.
Maximum minimalism. Smaller dependency footprint, fewer abstractions, faster cold starts. This can make a real difference for serverless functions or container images you ship frequently.

For everything else — typical CRUD APIs, internal services, anything where automatic docs and validation pull their weight — FastAPI's layer is worth the trade.

How the layers fit together

Here's where each layer takes over during a typical request:

Uvicorn receives bytes off the wire and translates them into ASGI events. Starlette runs the middleware stack and matches the route. FastAPI's layer parses data from the request, validates it with Pydantic, calls your function, and serializes the return data. Then control hands back to Starlette to send the response, and to Uvicorn to write it to the socket.

Almost every line of that flow is Starlette's, with FastAPI bracketed in the middle to handle the type-driven work.

Starlette vs FastAPI: where the layers end

"FastAPI built on Starlette and Pydantic" is more than a tagline. It's an architectural decision that shows up everywhere in the Starlette vs FastAPI stack. The async support, middleware, WebSockets, routing, and request and response objects all come from Starlette unchanged. Pydantic does the validation. FastAPI wires your function signatures to both, plus dependency injection and OpenAPI on top.

Once you know where the seams are, a lot of things get easier: debugging middleware, picking a framework for a small service, reading stack traces, and understanding what's running underneath your code.

Whichever side of the Starlette vs FastAPI stack you end up on, you'll still need to know when things break in production. Honeybadger catches unhandled exceptions in your FastAPI or Starlette app, groups duplicates, and notifies you with the request context attached. Sign up for a free developer account and start monitoring your apps.

How a status page can show a site at its best (and 10 examples)

2026-07-15T07:00:00+00:00

Your status page is a bridge to your customers. It’s where you show what you can do and prove that your product is more than just sales talk. Though easy to overlook, it provides an opportunity to showcase all that’s best about your services.

The trick is how to do it well. Fortunately, there are many outstanding status pages that you can draw inspiration from. Once your ideas take shape, you're ready to present your vision to customers.

In this article, you’ll learn what a public status page can do, why you should have one, and what it takes to make a good one. After that, we'll run through some status page examples that show what others have achieved with their pages, and then we'll show how easy it is to set up a status page using Honeybadger.

Why is it important to have a public status page?

Using your services is an act of faith that you need to earn and then repay. Customers want to know they can trust you, and a public status page lets you demonstrate your reliability. If you’re achieving 100% uptime, it’s the place to show it off.

It’s a plain-speaking, fact-driven demonstration of your commitment to your customers and a showcase of your ability to deliver a useful, usable product. Your status and incident communication skills are a key part of customer relationship management.

Strong metrics on your page show that you can help your customers achieve their own goals. However, when things do go wrong, being transparent about it via a dedicated status page makes it less disruptive. It’s less of a shock if users understand the situation or receive advance notice of scheduled maintenance. They can see what’s happening and that you're working to resolve the issue.

What should a strong status page include?

A good status page isn’t just about looking good. It’s about presenting information your clients need, and helping them find it. Here are some points you should consider when designing your page.

Clarity: The main function of a status page is to let users know that your services are running. Function takes precedence over form, though it never hurts if your site is pleasant to look at. Easily readable and findable information ensures your users have a positive experience.
Metrics: Uptime is the key metric for a status page, but general service health and response times matter too. You don’t have to be comprehensive, but presenting additional data can help. Showing planned maintenance or scheduled downtime is also useful, as is providing date switchers to change the displayed periods.
Links: The dual goals of presenting information while keeping things simple can be at odds with each other. Links can provide further information to those who need it without cluttering things for everyone else. A link to your support page or to any of your other online services is also a good idea.

10 great status page examples

Now that we've looked at the theory, let's take a look at some of the best status page examples. These great examples show the system status for various services, displaying metrics like historical uptime, response times, and third-party service info. Most have a user-friendly interface and show detailed status updates whenever there's a change. Studying these can help you decide what to include on your own page.

Wistia

As well as uptime, Wistia shows you its media processing time history

Wistia is a video management platform for those looking for something a little more businesslike than YouTube. Its status page packs in plenty of information, but still manages to be clear and readable. You can see what’s happened over the last 90 days, with more detail available by mousing over each day, and there are options to change the period shown. There’s also a useful graph showing media processing wait time. The page also includes incident reporting and various other information channels.

Strengths: Comprehensive. Readable. Crisp.

Okta

Okta’s page includes a reassuring tick, and a calendar showing service disruptions

Okta is an identity and access management platform. Its site strikes a useful balance between simplicity and detail. There’s a nice big tick to quickly show that things are working, followed by a single page of alphabetically listed services that provide more specific information.

There’s an unusual calendar display that shows you what’s happened over the past month, too. The site’s clear design and color coding show you what’s going on without you needing to figure anything out. There are also various useful links.

Strengths: Straightforward. Original. Detailed.

Flare

Flare’s status page makes it very easy to check uptime and performance-related information

Flare is a cybersecurity tool that helps ensure user identities can be trusted. Like all good public status pages, it lets you see at a glance how its various services are performing. Mousing over any particular date brings up a pop-up with more information, though the animation is slightly off-putting. You can also flip the display between uptime and performance, and there are easy controls to change the displayed period.

Strengths: Interactive. Adjustable. Powerful.

Deno

Deno’s minimal style oozes calmness and authority

Deno is an open-source JavaScript runtime with a status page that reflects the technical prowess of its product. As well as looking sleek, cold, and moody, the page's logo speaks to our affinity for stylish animals. The page is very clear and provides plenty of additional information via expanders. Its informational pop-ups work well. We suspect whoever designed this knows their CSS stuff, and perhaps adds neons to their PC.

Strengths: Cool. Elegant. Reliable.

Harvard

Harvard's status page has a friendly look to it

Harvard is one of the world's most renowned educational institutions. Its status page has a pastoral quality. It uses a subtle green that nods to the header image of the Harvard Yard. In addition to showing the status of various services, it provides useful links that help students easily solve their problems.

Strengths: Calm. Reassuring. Pastoral.

Graphite

Graphite's status page looks cool, but not at the expense of usability

Graphite is an AI code review platform pitched at developers. Its status page uses green and oozes cold technical sophistication. Its mouseover popups provide additional details, and there's a clear, readable incident log. The only downside is the mildly confusing empty pop-ups on incident-free days.

Strengths: Slick. Clear. Classy.

PagerTree

PagerTree's status page is easy to understand, but contains plenty of useful information

PagerTree is a management system for on-call teams. Its bold, clear page includes a brief list of services, with response times and uptime listed in each row. As well as being easy to understand, it includes technical data, and you can click on each day to see more.

Strengths: Bold. Organized. Informative.

Docker

Docker’s status page provides graphs of uptime and response time

Docker is a containerization system that makes deploying software easier and more secure. Its status page is efficient and informative, with details of each service available on mouseover and plenty of metrics below. Docker users are likely to be technical and to pay close attention to performance, reflected in the selection of response-time metrics alongside the more common uptimes on display.

Strengths: Metrics. Efficiency. Detailed.

Vimeo

Vimeo's well-organized page fits all its services onto a single screen

Vimeo is a professionally oriented video platform. Its status page shows off its professionalism, with simple ticks indicating that services are working. It also manages to get all its services onto a single page, with a clear incident log underneath. A few links at the top provide additional information.

Strengths: Orderly. Organized. Compact.

RubyGems

RubyGems uptime page is clear, but packs all the important details

RubyGems lets Ruby users and developers share code packages. Its uptime status page is simple, clean, and easy to understand. Delivered by Honeybadger, it shows both response times and uptime and makes it clear what has been happening recently, which in this case is nothing bad. Its three main services are each displayed on a single line, with their metrics clearly labeled.

As well as being clear enough to read at a glance, it also packs details into its design that you can see without having to scroll or hunt around to find. You can click on individual days to view more detailed metrics, too.

Strengths: Tidy. Detailed. Powerful.

Issues to look out for when creating a status page

When you’re creating a status page, there are a few key things to consider.

Is your status page easy to manage?

You want the status page to take care of itself once it's up. Ideally, it should be able to grab data automatically. It should handle outages across any of its data sources and show that the services have been restored when they come back online.

It should be able to dynamically adjust the display period if that’s relevant, perhaps highlighting longer periods of uptime. If not, it should be easy for you to change—and that goes for all changes you want to make.

If you have an incident log, it should be easy to update, preferably by pulling data directly from your logging system, with an easy way to edit it if you need to provide users with more specific details.

Does your status page integrate well with monitoring tools?

Status pages need data; the more the better. Wiring it all up manually is one approach, but it's slow and expensive. Automatically piping it in is faster and more efficient. Honeybadger gives you a simple set of tools to do that, with key features such as uptime checking and cron job monitoring, so you can use it to track services that might otherwise be tricky to monitor.

Incident management features are great to have too, allowing you to report to your users, provide a comprehensive overview of your service status, and significantly enhance the customer experience. Atlassian Statuspage has these, as does Honeybadger.

Is your status page showing users what they want?

Simplicity is key here. Most of the pages listed above are not flashy. Why? Customers are in a rush—possibly even a panic—when they struggle to connect to a service. They don’t want to be distracted. They need to know what’s going on, quickly.

Visually appealing status pages are fantastic, but utility should always be the priority. Make sure your page aligns with what your users want and need (which aren’t always the same thing). This requires some empathy. Gathering quality feedback can help, and providing a quick way for users to contact you on your status page may also help you understand their needs.

How to create the best status page in Honeybadger

Now that we know what makes the best status pages great, it's time to set up our own. Fortunately, Honeybadger makes that very easy. It provides hosted status pages that include several advanced features.

With it, you can create a status page in just a few clicks. With a little more work, you can also integrate with its monitoring tools, letting you check your uptime or monitor cron jobs, for example. Honeybadger also has incident management features, letting you inform users about recent events. As well as a website, you can use a Honeybadger status page to monitor your apps, APIs, or other services.

To begin, you first need a Honeybadger account, so go to Honeybadger’s homepage and create one if you haven’t already.

Next, navigate to Honeybadger's status page management screen, then click the “Create your first status page” button. You could also check out the guide to uptime monitoring if you want to learn more.

Clicking this button is the first step to getting your own page set up

That will take you to the new status page screen. Give your page a name and fill in the details as needed.

The new status page screen is nice and simple, but also contains powerful extras

You can also display a message to users of your application or website, connect Google Analytics, and more. Business accounts can add password protection and extra customizations.

When you're ready, click “Create Page,” and voila, your page will be created. It could hardly be more user-friendly. It follows a basic status page template. There are controls that let you edit or delete your page, create incidents, view ongoing incidents, and view a log of historical data.

Here's the page in all its glory.

Here’s a newly created Honeybadger status page

This is just a taste of what you can do. From here, you can add a logo, including a separate one for dark mode. You can add a favicon too, so it matches your site. You can also attach your own custom domain. Take a look through the Honeybadger documentation to learn what else is available.

Creating a status page is easier than you think with Honeybadger

A status page is a key part of your product offering, helping you keep users informed and building trust with customers. Building one shouldn’t be an afterthought. Take care to build one that delivers everything your clients want and shows your ability to deliver a consistently reliable product.

If these status page examples have inspired you, it's time to start working on your own. Fortunately, you can have a well-designed status page ready within minutes. Sign up for a free trial of Honeybadger and see how easy it is to build your own.

Next.js error handling: a practical guide

2026-06-18T07:00:00+00:00

Every Next.js application has to deal with errors, whether it's a failed API call, invalid user input, or a bug that slips into production. The App Router gives you built-in tools to handle each of these cases differently, keeping your UI intact and your users informed.

No matter how carefully you write your code, things will go wrong. An API will go down, a user will submit unexpected input, or a bug will surface in production. Next.js error handling, especially with the App Router, gives you a structured way to deal with both the errors you expect and the ones that catch you off guard. In this article, I'll walk you through how to handle errors at every level of a Next.js application and show you how to integrate Honeybadger so that no error goes unnoticed.

Handling expected errors

Expected errors are the ones you can anticipate: a user submits a form without filling in the required fields, an API request returns a 404, or an authentication check fails. These aren't bugs. They're normal outcomes of how web applications work. The key principle in Next.js is to model expected errors as return values, not thrown exceptions. You return a value that describes what went wrong and let the UI respond accordingly.

Server Actions

Let's start with Server Actions. Imagine you have a form that lets users create a new blog post. The Server Action needs to validate the input and communicate with an API, and either step could fail:

// app/actions.ts
'use server'

export async function createPost(prevState: any, formData: FormData) {
  const title = formData.get('title')

  if (!title || typeof title !== 'string' || title.trim().length === 0) {
    return { message: 'Title is required.' }
  }

  const res = await fetch('https://api.example.com/posts', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ title: title.trim() }),
  })

  if (!res.ok) {
    return { message: 'Failed to create post. Please try again.' }
  }

  // If we get here, everything worked
}

Instead of throwing an error, the function returns an object with a message property. On the client, you consume this with React's useActionState hook:

'use client'

import { useActionState } from 'react'
import { createPost } from './actions'

export function PostForm() {
  const [state, formAction, pending] = useActionState(createPost, { message: '' })

  return (
    <form action={formAction}>
      <label htmlFor="title">Post Title</label>
      <input id="title" type="text" name="title" required />
      <button type="submit" disabled={pending}>
        {pending ? 'Creating...' : 'Create Post'}
      </button>
      {state?.message && (
        <p role="alert" className="error">{state.message}</p>
      )}
    </form>
  )
}

The hook gives you the current state (including the error message), the form action, and a pending boolean. When the Server Action returns an error, the component re-renders and the error message appears below the form. The user sees exactly what went wrong and can try again.

Server Components

In Server Components, you can check whether a request succeeded and conditionally render different UI:

export default async function PostPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  const res = await fetch(`https://api.example.com/posts/${id}`)

  if (!res.ok) {
    return (
      <div className="error-state">
        <h2>Could not load this post</h2>
        <p>The server returned an error. Please try again later.</p>
      </div>
    )
  }

  const post = await res.json()

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </article>
  )
}

You fetch data, check the response, and if it's not ok, you return a fallback UI instead of the normal content. This same pattern works when you fetch data in any Server Component.

Handling 404s with `notFound()`

Next.js provides a dedicated notFound() function from next/navigation for the 404 case. When you call it, Next.js stops rendering the current page and shows a 404 UI instead:

import { notFound } from 'next/navigation'

export default async function PostPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  const post = await getPost(id)

  if (!post) {
    notFound()
  }

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </article>
  )
}

By default, Next.js renders a generic 404 error page when notFound() is called. But you can create a custom error page by adding a not-found.tsx file in the same route segment. For example, if you place a not-found.tsx file inside app/blog/, it will render your custom error page whenever notFound() is called from any page within that route segment.

Handling uncaught exceptions

The other type of error is the ones you didn't see coming — a null reference, a third-party library throwing unexpectedly, or a network request failing in a way you didn't account for. These are actual bugs. Next.js handles them with error boundaries, a React concept where a component catches errors during rendering and displays a fallback UI instead of crashing the entire component tree. The App Router builds this directly into the file system routing convention.

The error.tsx convention

Create a file called error.tsx in any route segment. It must be a Client Component and receives two props: the error object and an unstable_retry function that lets the user try again (the unstable_ prefix means this API may change in a future release):

// app/dashboard/error.tsx
'use client'

export default function DashboardError({
  error,
  unstable_retry,
}: {
  error: Error & { digest?: string }
  unstable_retry: () => void
}) {
  return (
    <div className="error-container">
      <h2>Something went wrong</h2>
      <p>An unexpected error occurred while loading the dashboard.</p>
      <button onClick={() => unstable_retry()}>Try again</button>
    </div>
  )
}

When an uncaught error occurs anywhere within the app/dashboard/ route segment or its children, Next.js will catch the error and render this fallback UI instead of crashing the page. The unstable_retry function re-renders the segment without a full page reload, which is handy for transient errors like network timeouts.

Note the digest property on the error object. When a server-side error occurs, Next.js replaces the original error message with a hash to avoid leaking sensitive details like database queries or file paths. The full error message stays in your server-side logs.

Nested error boundaries

Errors bubble upward through the route hierarchy until they hit the nearest error boundary, so you can be strategic about where you place your error.tsx files.

For example, imagine a dashboard with a sidebar and a main content area. By placing error.tsx at the right level, you can contain a crash to just the affected area while keeping the sidebar functional:

app/
  dashboard/
    error.tsx          # Catches errors from all dashboard child routes
    layout.tsx         # Dashboard layout with sidebar (stays intact)
    page.tsx           # Main dashboard page
    analytics/
      error.tsx        # Catches errors only in the analytics section
      page.tsx
    settings/
      page.tsx         # Errors here bubble up to dashboard/error.tsx

If the analytics page crashes, only that section shows the error UI — the sidebar stays intact. If settings crashes, the error bubbles up to dashboard/error.tsx since it doesn't have its own error boundary.

global-error.tsx

error.tsx can't catch errors in the root layout since it wraps everything. For that, Next.js provides app/global-error.tsx, which replaces the entire page when triggered and must define its own <html> and <body> tags:

// app/global-error.tsx
'use client'

export default function GlobalError({
  error,
  unstable_retry,
}: {
  error: Error & { digest?: string }
  unstable_retry: () => void
}) {
  return (
    <html>
      <body>
        <div className="global-error">
          <h2>Something went wrong</h2>
          <p>We encountered an unexpected error. Please try refreshing the page.</p>
          <button onClick={() => unstable_retry()}>Try again</button>
        </div>
      </body>
    </html>
  )
}

In practice, errors in the root layout are rare, but having a global error page in place ensures your users never see a completely broken page.

Event handler errors

There's an important limitation to be aware of: error boundaries only catch errors that occur during rendering. If an error happens inside an event handler, like an onClick or onSubmit callback, the nearest error boundary won't catch it because event handlers run outside of React's rendering cycle.

For these cases, you need to catch errors manually with a try/catch block:

'use client'

import { useState } from 'react'

export function DeleteButton({ id }: { id: string }) {
  const [error, setError] = useState<string | null>(null)

  const handleDelete = async () => {
    try {
      const res = await fetch(`/api/posts/${id}`, { method: 'DELETE' })
      if (!res.ok) {
        setError('Failed to delete this post. Please try again.')
      }
    } catch (e) {
      setError('Something went wrong. Please check your connection.')
    }
  }

  return (
    <div>
      <button onClick={handleDelete}>Delete</button>
      {error && <p role="alert" className="error">{error}</p>}
    </div>
  )
}

This is a common pattern in client-side error handling. One exception: if you use useTransition and throw an error inside startTransition, that error will bubble up to the nearest error boundary, even from an event handler.

Capturing and reporting Next.js errors with Honeybadger

Proper error handling in the UI is one thing, but in production, you also need to know when errors are happening, how often, and what's causing them. Users almost never report bugs, and digging through server-side logs is tedious at best.

Honeybadger's Next.js integration plugs into your application to automatically catch errors on both the server side and client side, group duplicates, and notify you with enough context to actually fix things.

Installation and setup

First, install the required packages:

npm install @honeybadger-io/react @honeybadger-io/nextjs

Then run the setup command to generate the configuration files:

npx honeybadger-copy-config-files

This creates configuration files for the server, client, and edge runtimes, as well as error.tsx and global-error.tsx files for the App Router. Next, add your API key to your environment variables:

NEXT_PUBLIC_HONEYBADGER_API_KEY=your_api_key
NEXT_PUBLIC_HONEYBADGER_REVISION=your_deployment_revision

Finally, wrap your Next.js config with Honeybadger's setup function to enable source map uploads and error reporting:

// next.config.js
const { setupHoneybadger } = require('@honeybadger-io/nextjs')

const nextConfig = {}

module.exports = setupHoneybadger(nextConfig)

Source maps are uploaded automatically, so stack traces in Honeybadger point to your original source code instead of minified bundles.

Wrapping your app with the error boundary

Wrap your application with Honeybadger's error boundary in your root layout so any unhandled React component error is automatically reported:

// app/layout.tsx
import { Honeybadger, HoneybadgerErrorBoundary } from '@honeybadger-io/react'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <HoneybadgerErrorBoundary honeybadger={Honeybadger}>
          {children}
        </HoneybadgerErrorBoundary>
      </body>
    </html>
  )
}

Honeybadger will now capture uncaught client-side exceptions and React component errors. You can also add the showUserFeedbackFormOnError prop to show a feedback form when an error occurs, letting users describe what they were doing.

Manual error reporting

For errors you handle gracefully but still want to track, use Honeybadger.notify():

import { Honeybadger } from '@honeybadger-io/react'

try {
  await submitOrder(orderData)
} catch (error) {
  Honeybadger.notify(error)
  return { message: 'Order failed. Please try again.' }
}

You can also attach context to help with debugging:

Honeybadger.setContext({
  user_id: currentUser.id,
  user_email: currentUser.email,
})

When an error shows up in Honeybadger's dashboard, you'll know exactly which user was affected and have a full stack trace pointing to the exact line of code.

Next.js error handling best practices

To recap, here's how I think about Next.js error handling.

For expected errors, return values instead of throwing. Use useActionState in Server Actions and conditional rendering in Server Components to handle errors gracefully. Use notFound() for missing resources instead of rolling your own 404 logic.

For uncaught exceptions, place error.tsx files at the right levels of your route hierarchy so a crash in one section doesn't take down the whole page. Add global-error.tsx as a safety net for root layout errors. And remember that error boundaries don't catch errors in event handlers, so you'll need try/catch there.

Finally, don't rely on users to tell you when things break. Set up error monitoring so you find out about production issues before your users do.

That covers the full picture of error handling in Next.js, from data fetching and form validation to production error management. If you want to try Honeybadger with your Next.js project, you can sign up for a free trial and have error reporting running in a few minutes.

Next.js vs React: What’s the difference and which should you use?

2026-05-28T07:00:00+00:00

The Next.js vs React question is not really a comparison between two competing tools — Next.js is built on top of React. React itself is a UI rendering JavaScript library used for building user interfaces across platforms, including web applications and mobile apps with React Native, while Next.js is a framework that wraps React and makes concrete decisions about routing, data fetching, and server-side concerns. Understanding this relationship is the starting point for every project decision you will make when building web applications.

React handles one job extremely well: taking a component tree and turning it into DOM output, then reconciling changes efficiently. Every other layer like how you fetch data, how you route between pages, what runs on the server versus the client is deliberately left to the developer or to third-party libraries. Next.js packages those decisions into a cohesive framework, adding server-side rendering, file-system-based routing, built-in image optimization, and an API routing layer that runs alongside your JavaScript code. This makes it particularly useful for complex projects that require coordination between the front-end and back-end.

This article covers what each tool does at a technical level, how they differ in behavior and file structure, how their rendering modes work, and answers the common question: what is Next.js vs React in practical terms?

What is React?

React's core contribution to web development is the component-based architecture combined with a virtual DOM diffing algorithm. Before React, updating the DOM in response to state changes meant either re-rendering entire page sections or writing granular imperative update logic that quickly became unmaintainable.

React introduced a declarative model: describe what the user interface should look like for a given state, and let the reconciler determine the minimum set of real DOM mutations required. This approach transformed web development workflows and made React a widely adopted JavaScript library for building complex user interfaces.

The component and hook model

A React component is a function that accepts props and returns JSX. The function re-runs whenever its state or props change, and React reconciles the output against the previous virtual DOM snapshot. Hooks like useState and useEffect let you attach stateful behavior and side effects to functional components without resorting to class syntax.

In practice, components are composed hierarchically, where child components receive data and callbacks from their parents. This composition model is what enables React to scale cleanly in complex projects, especially when managing deeply nested user interface trees.

// src/components/UserCard.tsx

import { useState, useEffect } from 'react';

interface User {
  id: number;
  name: string;
  email: string;
}
interface UserCardProps {
  userId: number;
}

export function UserCard({ userId }: UserCardProps) {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetch(`/api/users/${userId}`)
      .then((res) => res.json())
      .then((data) => {
        setUser(data);
        setLoading(false);
      });
  }, [userId]);

  if (loading) return <div>Loading...</div>;
  if (!user) return <div>User not found</div>;

  return (
    <div className="card">
      <h2>{user.name}</h2>
      <p>{user.email}</p>
    </div>
  );
}

This component fetches a user when the userId prop changes, tracks the loading state, and renders conditionally based on that state. The useEffect dependency array [userId] ensures the fetch only re-runs when userId changes, not on every render. This pattern is idiomatic React, but notice that the data fetch happens entirely in the browser after the component mounts. There is no concept of running this on a server.

What React deliberately leaves out

React provides no routing system. Navigation between views requires installing a library like React Router or TanStack Router. React also has no built-in data fetching convention, no server-side rendering pipeline, no image optimization, and no API routes server. You can combine React with Express for server-side rendering and with third-party libraries like SWR or TanStack Query for caching, but you must assemble these pieces yourself across multiple JavaScript files.

This is not a weakness. For applications that run entirely in the browser, including dashboards and progressive web apps, the absence of framework opinions means less configuration overhead and more flexibility in your dependency choices. The cost is that you own the architecture decisions.

React also benefits from a large and active community, which means most problems you encounter already have established patterns or libraries.

What is Next.js and how does it extend React?

Next.js extends the React component model with conventions and runtime capabilities that React itself does not provide. The two most significant additions are the rendering pipeline (Server-Side Rendering (SSR), Static Site Generation (SSG), and Incremental Static Regeneration (ISR)) and the file-based routing system. Everything else—like API handling, image optimization, the Edge Runtime, font loading, and middleware—builds on top of those two foundations.

The App Router and Server Components

Next.js 13 introduced the App Router, which changed the default rendering model. In the App Router, every component is a React Server Component (RSC) unless you explicitly opt out with the 'use client' directive.

Server Components render on the server, can await async operations directly in the component body, and never ship their JavaScript code or the data-fetching JavaScript libraries they use to the client bundle. This results in automatic code splitting, where only the required interactive parts of the application are sent to the browser.

// app/users/[id]/page.tsx - runs on the server, zero client JS

interface PageProps {
  params: Promise<{ id: string }>;
}

async function getUser(id: string) {
  const res = await fetch(`https://api.example.com/users/${id}`, {
    next: { revalidate: 60 }, // ISR: revalidate this data every 60 seconds
  });
  if (!res.ok) throw new Error('Failed to fetch user');
  return res.json();
}

export default async function UserPage({ params }: PageProps) {
  const { id } = await params;
  const user = await getUser(id);
  return (
    <main>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
    </main>
  );
}

This is fundamentally different from the React example above. The component is declared async and awaits the data directly, without useEffect, useState, or state management libraries. The fetch happens at request time on the server. The client receives pre-rendered HTML. The next: { revalidate: 60 } option activates Incremental Static Regeneration, so after the initial render, Next.js regenerates the page in the background when a request arrives after 60 seconds, serving the stale version until the fresh one is ready.

Client Components and the 'use client' boundary

When a component needs interactivity, you add 'use client' at the top of the file. This converts the component to a Client Component, which is hydrated in the browser. The boundary between Server and Client Components is explicit and composable: a Server Component can render interactive child components, but a Client Component cannot render a Server Component directly. This separation enables granular automatic code splitting and reduces bundle size.

// app/components/AddToCartButton.tsx
'use client';

import { useState } from 'react';

interface AddToCartButtonProps {
  productId: string;
  price: number;
}

export function AddToCartButton({ productId, price }: AddToCartButtonProps) {
  const [added, setAdded] = useState(false);

  async function handleClick() {
    await fetch('/api/cart', {
      method: 'POST',
      body: JSON.stringify({ productId, quantity: 1 }),
      headers: { 'Content-Type': 'application/json' },
    });
    setAdded(true);
  }

  return (
    <button onClick={handleClick} disabled={added}>
      {added ? 'Added to cart' : `Add to cart- $${price}`}
    </button>
  );
}

The product page itself (a Server Component) fetches product data on the server and renders HTML, while interactive child components handle user interactions like adding items to a cart. This pattern keeps user interfaces fast and lightweight. This granular control over the client bundle size is one of the most architecturally significant advantages Next.js provides over a pure React SPA (Single Page Application).

Key differences

The divergence between Next.js and a standalone React application becomes concrete when you compare how each handles routing, the rendering pipeline, project layout, search engine visibility, and runtime performance. These are not surface-level configuration differences; they reflect fundamentally different execution models.

Routing

React has no router. You install React Router and configure routes manually across multiple JavaScript files. Next.js uses file-based routing. Creating a file automatically registers a route. This removes boilerplate and makes it easier to scale routing in complex projects.

// src/main.tsx - React + React Router v6

import { createBrowserRouter, RouterProvider } from 'react-router-dom';
import { RootLayout } from './layouts/RootLayout';
import { HomePage } from './pages/HomePage';
import { ProductPage } from './pages/ProductPage';
import { NotFound } from './pages/NotFound';
import ReactDOM from 'react-dom/client';

const router = createBrowserRouter([
  {
    path: '/',
    element: <RootLayout />,
    errorElement: <NotFound />,
    children: [
      { index: true, element: <HomePage /> },
      { path: 'products/:id', element: <ProductPage /> },
    ],
  },
]);

ReactDOM.createRoot(document.getElementById('root')!).render(
  <RouterProvider router={router} />
);

Next.js uses a file-based routing system. Creating a file at app/products/[id]/page.tsx automatically registers the route /products/:id. The folder structure is the route definition. Layouts, loading states, error boundaries, and not-found pages are handled by special files (layout.tsx, loading.tsx, error.tsx, not-found.tsx) placed in the corresponding route segment directory.

app/
├── layout.tsx          → root layout, wraps all routes
├── page.tsx            → renders at /
├── loading.tsx         → Suspense fallback for /
├── error.tsx           → error boundary for /
├── products/
│   ├── page.tsx        → renders at /products
│   └── [id]/
│       ├── page.tsx    → renders at /products/:id
│       └── loading.tsx → Suspense fallback for /products/:id
└── api/
    └── cart/
        └── route.ts    → API endpoint at /api/cart

The file-system router removes an entire category of configuration work. You do not write route declarations, import pages manually, or manage a separate router configuration object. The trade-off is that your folder structure becomes load-bearing.

Rendering modes

A plain React application renders entirely in the browser. The server sends a mostly empty HTML document with a script tag, and React bootstraps the application in the client. This is client-side rendering (CSR). Next.js supports multiple rendering strategies and enables automatic code splitting at the route and component level. This significantly improves performance for large web applications. Search engines and users on slow connections both receive no meaningful content until the JavaScript parses, executes, and renders.

Next.js supports four rendering strategies, and you can mix them within a single application. Static site generation renders pages at build time, the HTML is computed once and served as a static file on every request.

Server-side rendering (SSR) renders on each request, allowing you to fetch fresh data per user or session. Incremental Static Regeneration (ISR) generates the page statically but revalidates it on a configurable interval. Client-side rendering is available for components marked with 'use client'.

// app/blog/[slug]/page.tsx

// Generate static paths at build time (static site generation)
export async function generateStaticParams() {
  const posts = await fetch('https://api.example.com/posts').then(r => r.json());
  return posts.map((post: { slug: string }) => ({ slug: post.slug }));
}

// Revalidate every 10 minutes (ISR)
export const revalidate = 600;

export default async function BlogPost({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const post = await fetch(`https://api.example.com/posts/${slug}`).then(r => r.json());
  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
    </article>
  );
}

The generateStaticParams function tells Next.js which slugs to pre-render at build time as part of static site generation. Setting revalidate = 600 on the module activates ISR. After ten minutes, the next request triggers a background regeneration. The page still serves instantly from cache while the fresh version is being built. This combination is the standard pattern for content-heavy sites: fast initial load time from static files, with eventual consistency as content changes.

SEO implications

Search engines index HTML content. A CSR React application sends an empty div; the content arrives only after JavaScript executes, which introduces indexing uncertainty and delays. Googlebot does execute JavaScript, but not instantly, and social media crawlers (Open Graph, Twitter Cards) typically do not execute JavaScript at all, meaning link previews for a CSR app will be blank.

Next.js pages rendered via server-side rendering or static site generation (SSG) deliver fully populated HTML on the initial response. You can set metadata like page titles, descriptions, Open Graph tags, and canonical URLs using the built-in Metadata API routes, which generate the correct <head> tags at render time on the server:

// app/products/[id]/page.tsx

import type { Metadata } from 'next';

interface PageProps {
  params: Promise<{ id: string }>;
}

export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
  const { id } = await params;
  const product = await fetch(`/api/products/${id}`).then(r => r.json());
  return {
    title: `${product.name} - Acme Store`,
    description: product.description,
    openGraph: {
      title: product.name,
      images: [{ url: product.imageUrl }],
    },
  };
}

export default async function ProductPage({ params }: PageProps) {
  const { id } = await params;
  const product = await fetch(`/api/products/${id}`).then(r => r.json());
  return <ProductDetail product={product} />;
}

Note that the fetch in generateMetadata and the fetch in the page component both request the same URL. Next.js deduplicates these automatically using the built-in fetch cache. The network request is made once, even though you wrote it twice. This is a concrete example of the framework reducing accidental complexity.

Quick reference for React vs Next.js:

When to use React on its own

Standalone React (scaffolded with Vite or Create React App) is the appropriate choice when your application does not need server-side rendering, has no SEO requirements, and benefits from a thinner dependency footprint. The most common category is authenticated internal tooling: admin dashboards, CRM interfaces, data visualization tools, analytics platforms, and developer consoles. These applications sit behind a login screen, and the route structure is driven by application state (using state management libraries) rather than URL semantics.

React can also be extended beyond the web using React Native, allowing you to reuse concepts and patterns when building mobile apps.

A Vite-based React setup produces a minimal project with fast web development server startup and highly optimized production builds via Rollup. There is no server process to manage, no framework conventions to learn, and no build-time rendering pipeline to reason about.

If your team is familiar with React but not with Next.js-specific concepts like the App Router, Server Components, or the distinction between server-side and client-side data fetching, a plain React setup removes that cognitive surface area.

# Scaffold a React + TypeScript app with Vite
npm create vite@latest my-app -- --template react-ts
cd my-app
npm install

# Install Router for client-side navigation
npm install react-router-dom

# Install TanStack Query for data fetching and caching
npm install @tanstack/react-query

This combination of Vite, React Router, and TanStack Query covers the needs of most internal web applications. TanStack Query handles caching, background refetching, loading, and error states, among other things—with considerably less boilerplate than manually managing state with useEffect. For web applications where all data fetching is client-side anyway, this stack is competitive with Next.js in terms of developer experience.

Integrating React into an existing back-end

Another valid use of standalone React is when you have an existing server-side framework like Rails, Django, Laravel, or Spring, and you want to embed React components into specific pages rather than migrate to a JavaScript-first stack.

Third-party tools like Inertia.js let Rails or Laravel applications render React components server-side and manage navigation without a full SPA migration. In this architecture, Next.js would be redundant: the host framework already handles routing and server rendering.

When Next.js makes more sense

Next.js makes more sense when your application needs server-side rendering (SSR) for SEO or performance, when you want to colocate your API routes with your front-end code, or when you are building a content-heavy site where static site generation with revalidation provides both performance and freshness.

Public-facing applications with SEO requirements

Marketing sites, e-commerce websites, documentation, blogs, SaaS landing pages, and any application where pages need to rank in search results are natural fits for Next.js. Unlike React, the ability to combine static generation for high-traffic stable pages with ISR for frequently changing content, and server-side rendering (SSR) for personalized or session-dependent pages—all within a single codebase—is architecturally easy to implement.

Consider a product listing page on an e-commerce site. You want the page to load instantly (static or ISR for performance), include accurate metadata for search engines and social sharing (server-side rendering or static site generation (SSG) for SEO), and show personalized pricing or stock information (partial hydration with a Client Component making a client-side fetch after the static shell renders).

All of this is expressible in Next.js with standard patterns; in a plain React SPA, it requires either a separate server-side rendering (SSR) infrastructure or accepting the SEO limitations of client-side rendering.

Full-stack applications without a separate API service

Next.js Route Handlers let you define API endpoints that run alongside your front-end code, share type definitions, and deploy together as a single unit. For web development projects where the API and the UI are maintained by the same team and the back-end complexity does not justify a separate service, this is a significant simplification:

// app/api/orders/route.ts - runs on the server, not in the browser

import { NextRequest, NextResponse } from 'next/server';
import { db } from '@/lib/db'; // direct database access from the API route
import { auth } from '@/lib/auth';

export async function GET(request: NextRequest) {
  const session = await auth();
  if (!session) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const { searchParams } = new URL(request.url);
  const page = parseInt(searchParams.get('page') ?? '1', 10);
  const limit = 20;

  const orders = await db.order.findMany({
    where: { userId: session.user.id },
    orderBy: { createdAt: 'desc' },
    skip: (page - 1) * limit,
    take: limit,
  });

  return NextResponse.json({ orders, page });
}

This API route has direct database access, it imports a Prisma client, queries the database, and returns JSON. The front-end components in the same codebase can call this endpoint with a simple fetch('/api/orders'). TypeScript types for the response can be shared between the route handler and the calling component without publishing a separate package or running a code generation step. For small to medium teams building full-stack web applications, this tight coupling is a feature, not a liability.

Server Actions for form handling and mutations

Next.js Server Actions allow you to define server-side mutation functions that can be called directly from Client Components without going through an explicit REST endpoint. This is the pattern to reach for when you need form submissions, data mutations, or any user-triggered server-side operation:

// app/actions/createPost.ts
'use server';

import { revalidatePath } from 'next/cache';
import { db } from '@/lib/db';
import { auth } from '@/lib/auth';

export async function createPost(formData: FormData) {
  const session = await auth();
  if (!session) throw new Error('Unauthenticated');

  const title = formData.get('title') as string;
  const content = formData.get('content') as string;

  await db.post.create({
    data: {
      title,
      content,
      authorId: session.user.id,
    },
  });

  revalidatePath('/blog'); // purge the cached blog listing
}

// app/blog/new/page.tsx
'use client';

import { createPost } from '@/app/actions/createPost';

export default function NewPostForm() {
  return (
    <form action={createPost}>
      <input name="title" placeholder="Post title" />
      <textarea name="content" placeholder="Write your post..." />
      <button type="submit">Publish</button>
    </form>
  );
}

The form's action prop accepts the createPost server action directly. When submitted, Next.js serializes the form data and sends it to the server function, which executes in the Node.js runtime with full access to the database and environment variables. The revalidatePath call purges the Next.js cache for the /blog route, so the updated post list appears on the next request without a manual cache invalidation step. This entire pattern (form, mutation, cache invalidation) requires no custom API endpoint.

Next.js vs React: The architectural decision

The separation is cleaner than it might initially appear. React alone handles use cases where the application runs entirely in the browser and focuses on user interfaces through a component-based architecture. It's ideal for internal tools, authenticated dashboards, and single-page web applications without SEO requirements. This includes building interactive user interfaces for internal tooling, where client-side rendering is perfectly acceptable. Add Next.js when your web application needs to deliver server-rendered HTML for SEO or performance, when you want to run server-side logic alongside your front-end without maintaining a separate service, or when the file-system router and built-in optimizations justify the additional framework layer.

The practical signal to watch for is the nature of your first meaningful page render. If a blank loading screen is acceptable because the web application sits behind authentication and your users do not discover it via search, React's CSR model is okay. If search engine visibility is important, or the site needs to be fast for unauthenticated users on variable network connections, the server-side rendering capabilities of Next.js are important features.

One area worth monitoring is the Server Components model. The RSC architecture changes how you reason about data fetching and bundle size in ways that are not entirely settled. The mental model of interleaving server and client components, managing cache invalidation with revalidatePath and revalidateTag, and understanding which dependencies run only on the server has a meaningful learning curve. For developers new to both React and Next.js, starting with plain React as a JavaScript library and introducing Next.js only when you need server-side rendering or static site generation is a lower-risk path than beginning with the full App Router feature set.

If you liked this article and want to learn more about JavaScript, join the Honeybadger newsletter.

SIEM alerts: everything you need to know

2026-05-21T07:00:00+00:00

Let's walk through setting up SIEM (Security Information and Event Management) alerts to monitor security threats in applications. We will explain what SIEM alerts are, why they're relevant with regard to application security, and provide practical examples of common alerts a developer could implement. We will show how to configure simple alerts with Honeybadger Insights.

What is SIEM?

SIEM (Security Information and Event Management) refers to a class of security platforms that aggregate logs and security events from many systems and analyze them to detect threats. Just like in action movies where a thief exploits an unguarded angle, attackers in the cyber world look for weaknesses. A SIEM system works by pulling data from many different sources across the organization, including security system logs, usual and unusual network traffic, and threat intelligence. The SIEM analyzes them in one place to detect suspicious behavior instead of these signals living in silos.

The main aim of SIEM is to be a correlation engine. It doesn’t just collect raw data; it connects the dots using rule-based correlation, statistical analysis, and sometimes machine learning. The SIEM system continuously evaluates events in real time to identify patterns that indicate a real attack, enabling faster threat detection across your environment. Correlation helps prioritize alerts, not necessarily reduce them automatically. What this means is fewer false positives and clearer signals that something genuinely malicious is happening.

The importance of SIEM alerts

Organizations often run dozens or even hundreds of disconnected security tools where each generates alerts that require attention. Analysts are forced to jump between dashboards and manually investigate events. SIEM system addresses this problem by acting as the central nervous system of security operations. It prioritizes alerts by severity to help analysts immediately focus on incidents that pose the greatest risk.

The attackers don't even discriminate based on the size of the organisation. Some do it for the challenge or fun of it. They target organizations of all sizes and take advantage of openings across applications and cloud infrastructure. A SIEM system provides the visibility and context needed to detect these potential threats early, before they cause serious damage. Much like ignoring a staged diversion at the front of a museum and spotting the real break-in at the back, SIEM becomes one of the most powerful defensive tools security teams have.

How to respond to SIEM alerts effectively

Responding to SIEM alerts effectively determines whether a security incident is quickly contained or allowed to turn into a breach. Alert incident response procedures must be built on preparation, documentation, and practiced workflows. The goal is not just to react, but to respond effectively.

Establish runbooks for common alert types: Runbooks define exactly what should happen when a specific alert is triggered. For example, when a credential stuffing alert fires, the runbook should outline verification steps such as checking whether multiple accounts are affected, containment actions like blocking the attacking IP range, and notification requirements, including informing affected users. By standardizing incident responses, runbooks ensure consistency and help less-experienced team members handle incidents correctly without improvising under pressure.
Triage alerts immediately upon receipt: The first moments after receiving an alert are very important. Spend some time determining whether the alert represents a genuine threat or requires deeper investigation. Review recent similar alerts to see if the event is part of a broader attack pattern. You can also query the SIEM using BadgerQL (Honeybadger's Query Language) for additional context.
Document investigation steps and findings: Every alert investigation should leave a record. When alerts turn out to be false, document why they were triggered and whether tuning adjustments can prevent recurrence. When alerts uncover real attacks, record the attack vector, affected systems, and remediation steps taken.
Implement automated containment where safe: Certain scenarios, such as IP-based attacks, benefit from automated containment. When an IP triggers credential stuffing alerts, it can be temporarily blocked at the firewall or web application firewall. This allows containment to happen within seconds rather than waiting for manual action. However, automation must be used carefully. Over-automation can disrupt legitimate users.
Coordinate incident response across teams: Security incidents often span multiple layers, including applications, infrastructure, and databases. The security team may analyze data of the attack method, development teams patch vulnerable code, and security operations teams apply network-level blocks. Clear communication channels are essential. Many organizations rely on dedicated Slack channels or conference bridges to coordinate effectively during active incidents.

SIEM alert examples and types

SIEM alerts fall into several categories based on detection method and threat type. Each category serves a distinct purpose in the comprehensive security monitoring efforts to improve the security posture. Some identify known attack patterns, and some detect subtle behavioral deviations and enforce regulations. Below is a list of SIEM alerts covering the top SIEM alerts by threat detection method and also internal and external threat types.

Signature alerts: Signature-based alerts match specific patterns in log data, such as SQL injection attempts in HTTP requests or known malware file hashes. These alerts trigger when logs contain exact strings or regular expression matches associated with attacks. For example, detecting ' OR '1'='1' in query parameters signals a potential SQL injection probe.
Anomaly alerts: Anomaly-based alerts establish behavioral baselines and flag deviations. If a user account typically authenticates from New York during business hours, a login from Singapore at 3 AM exceeds normal behavior thresholds. These alerts require sufficient historical data to build accurate profiles.
Threshold alerts: Threshold-based alerts trigger when event counts exceed defined limits within time windows. Failed authentication attempts provide a clear example: five failed logins from a single IP address within ten minutes might indicate credential stuffing, while 100 failed logins across different accounts suggest a broader attack.
Compliance threat alerts: Compliance reporting enforces regulatory requirements and internal policies. PCI-DSS mandates alerts for unauthorized access attempts to cardholder data, while HIPAA requires notification of protected health information access outside normal workflows. Compliance frameworks require alerting and auditing, but tuning is still necessary to avoid alert fatigue.

Configuring alert triggers and correlation rules

Alert triggers define the conditions that generate notifications for common SIEM solution alerts. Simple triggers evaluate single log entries, while complex triggers correlate events across time windows and security data sources. Start with high-confidence signatures for known attacks before layering in anomaly detection and behavioral analysis.

Authentication alerts should trigger on multiple unsuccessful login attempts, successful logins following failed attempts (credential stuffing success), logins from blacklisted IP addresses, and authentications occurring simultaneously from geographically distant locations. Configure these with appropriate thresholds; three failed attempts might be a typo, but fifteen suggests an attack. Time windows matter too; five failures over 24 hours are less significant than five failures in sixty seconds.

Alerts on the application side monitor for injection attacks, path traversal attempts, and malicious file uploads. Web application firewalls generate logs that SIEM systems ingest and analyze. When requests attempt to access restricted file paths, or when uploaded files contain executable code. These alerts benefit from whitelisting safe patterns to reduce false positives from legitimate applications or user behavior.

Data access alerts flag unusual database queries, excessive record retrieval, and access to sensitive data outside normal application workflows. A user downloading sensitive data, such as customer records, at 2 AM warrants investigation, even if their credentials authenticate successfully. Configure these alerts to understand normal data access patterns.

Reducing false positives through SIEM alerts best practices

Reducing false positives is a core part of SIEM system alerts best practices, as excessive noise diminishes trust in alerting systems. Tuning requires iterative refinement based on investigation outcomes and environmental knowledge.

Whitelist known-safe activities that trigger alerts. Automated security scanners, monitoring systems, and internal tools often generate traffic patterns resembling attacks. Document these sources and exclude them from triggering alerts. For example, vulnerability scanners probe for SQL injection vulnerabilities as part of routine testing; their IP addresses should be whitelisted to prevent false alarms during scheduled scans.

Context development could add business intelligence to raw security events. An alert showing "100 failed login attempts from 203.0.113.45" provides limited context. Combining this with evolving threat intelligence reveals whether the IP belongs to a known botnet, including geolocation, which shows the attack origin, and correlating with past incidents indicates if this IP has targeted the organization previously.

Alert aggregation prevents duplicate notifications for the same incident. When an attacker probes multiple endpoints, each probe might trigger individual alerts. Aggregate these into a single incident showing the attack's scope rather than flooding the team with hundreds of similar notifications.

Managing alert fatigue and team burnout

Alert fatigue occurs when you receive so many notifications that they become desensitized, and you miss important security incidents. If your company receives hundreds of alerts a day, you're likely to get low investigation rates, with analysts ignoring the bulk of alerts.

Implement alert scoring that combines severity, context, and historical accuracy. Alerts that frequently lead to confirmed security incidents receive higher scores than those with poor signal-to-noise ratios. Machine learning models can predict which alerts warrant investigation based on key components like time of day, user reputation scores, and historical attack patterns. This scoring helps security analysts prioritize workloads when alert volumes exceed capacity.

Establish alert ownership and escalation paths. Each alert type needs a designated team responsible for investigation and remediation. Application security alerts route to security teams familiar with the codebase, infrastructure alerts go to operations, and access control alerts might escalate to the security team. Clear ownership prevents alerts from languishing in shared queues where everyone assumes someone else will investigate.

Setting up alerts with Honeybadger Insights

Applications generate a constant stream of events like failed logins, suspicious input, permission changes, and unexpected system or user behavior. Instead of sending raw log files into a traditional SIEM system pipeline and configuring complex agents, Honeybadger Insights is an observability tool that gives you structured security events directly from your application. These events become searchable, filterable, and alertable. This allows you to detect and respond to potential threats in real time without heavy infrastructure.

The idea is simple: treat security threats like application telemetry. Whenever something suspicious happens, you send a structured event to Honeybadger Insights. Then you create queries and alerts that behave like SIEM system rules.

For this guide, we will work with Nodejs. First, install the Honeybadger JavaScript package in your Node.js application. This example uses a basic Express server that reports failed login attempts.

npm init -y
npm install express @honeybadger-io/js

Create a file named server.js and configure Honeybadger.

const express = require("express");
const Honeybadger = require("@honeybadger-io/js");
const app = express();

app.use(express.json());

// Initialize Honeybadger
Honeybadger.configure({
  apiKey: process.env.HONEYBADGER_API_KEY,
  environment: "production",
});

// Simulated login endpoint
app.post("/login", (req, res) => {
  const { username, password } = req.body;

  // Fake authentication logic
  const isValid = username === "admin" && password === "secret";

  if (!isValid) {
    // Send a SIEM-style security event to Honeybadger Insights
    Honeybadger.event({
      event_type: "security.login.failed",
      user: username,
      ip: req.ip,
      timestamp: new Date().toISOString(),
      metadata: {
        reason: "Invalid credentials",
      },
    });

    return res.status(401).json({ error: "Invalid credentials" });
  }

  res.json({ message: "Login successful" });
});

// Example: suspicious input detection
app.post("/search", (req, res) => {
  const { query } = req.body;

  if (query && query.includes("' OR 1=1")) {
    Honeybadger.event({
      event_type: "security.sql_injection.detected",
      ip: req.ip,
      query,
      timestamp: new Date().toISOString(),
    });
  }

  res.json({ results: [] });
});

app.listen(3000, () => {
  console.log("Server running on port 3000");
});

In this setup, each security action is shown as a structured event. Instead of parsing logs later, Honeybadger stores these events in Insights, where they can be queried like a lightweight SIEM system dataset.

To run the code locally, create a .env file or export your API key in the terminal:

export HONEYBADGER_API_KEY=your_api_key_here

Start the server:

node server.js

Then simulate events using curl or Postman:

curl -X POST http://localhost:3000/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"wrong"}'

Each failed request will appear in Honeybadger Insights within seconds. You can repeat the request multiple times to trigger your alert thresholds.

After events start flowing, you can configure SIEM-style alerts inside Honeybadger. For example, here's a query to find the security.login.failed events:

fields @ts, @preview
| filter event_type::str == "security.login.failed"
| sort @ts

Honeybadger can alert you when the event count exceeds a threshold within a time window. This allows you to detect brute-force attacks, suspicious traffic spikes, or repeated injection attempts. You can also filter by IP address, user, environment, or any custom alert metadata you send.

After configuring the Insights query, you can create an alarm by clicking the triple dots in the events panel. Once you've selected "Build alarm", you'll be taken to a new setup screen that looks something like this:

Here, the alert has already been triggered—you can set thresholds, lag times, and other settings. Alarms also have their own dashboard, where you can find an overview of their status.

This approach turns your application into the primary source of security intelligence. Instead of forwarding system logs and building fragile parsing rules, Honeybadger alerts your team about events at the moment the risk occurs. The result is faster threat detection, cleaner security data, and SIEM-style security monitoring without the operational overhead of traditional security pipelines.

If you want to take this further, you can extend the pattern to permission changes, rate-limit violations, token misuse, or unusual API access patterns. You can read more about everything queries can do in the Insights documentation.

Benefits of Honeybadger for SIEM alerts

Traditional enterprise SIEM solutions require significant investment in licensing, infrastructure, and specialized personnel. Other security solutions like Splunk, QRadar, and ArcSight need you to have a dedicated security operations center and security teams trained in complex query languages. These platforms also require deep integration work to connect with your existing infrastructure and other security tools already in your stack.

That's not the case for Honeybadger compared to other tools used for security event management. It removes these barriers through developer-focused integration, so you focus more on improving security posture. Setup takes minutes, and installing the package requires just a few commands. The platform automatically captures events through existing error and performance monitoring instrumentation, which lets you enhance threat detection capabilities (improve security posture) without overhauling your entire toolchain.

Alert configuration happens through intuitive web interfaces. Creating a SIEM solution alert resembles configuring a performance threshold, which involves selecting the event pattern, defining the threshold, and specifying notification channels. Structured logging lets you query and analyze data immediately. Notifications integrate seamlessly through Slack, PagerDuty, and webhooks. The platform combines SIEM system capabilities with error tracking and performance monitoring in a single interface to provide a unified dashboard for security incident investigation.

You can sign up for a free trial of Honeybadger to see if this will fit your company’s needs.

Test-Commit-Revert: A useful workflow for testing legacy code in Ruby

2020-10-06T00:00:00+00:00

It happens to all of us. As software projects grow, parts of the production code we ship end up without a comprehensive test suite. When you take another look at the same area of code after a few months, it may be difficult to understand; even worse, there might be a bug, and we don't know where to begin fixing it.

Modifying production code without tests is a major challenge. We can't be sure if we'll break anything in the process, and checking everything manually is, at best, prone to mistakes; usually, it's impossible.

Dealing with this kind of code is one of the most common tasks we perform as developers, and many techniques have focused on this issue over the years, such as characterization tests, which we discussed in a previous article.

Today, we'll cover another technique based on characterization tests (test-commit-revert) and introduced by Kent Beck, who also introduced TDD to the modern programming world many years ago.

What's TCR?

TCR stands for "test, commit, revert", but it's more accurate to call it "test && commit || revert". Let's see why.

This technique describes a workflow to test legacy code. We'll use a script that will run the tests every time we save our project files. The process is as follows:

First, we create an empty unit test for the part of the legacy code we want to test.
We then add a single assertation and save the test.
Since we have our script set up, the test is automatically run. If it succeeds, the change is committed. If the test fails, the change is deleted (reverted), and we need to try again.

Once the test passes, we can then add a new test case.

Essentially, TCR (test, commit, revert) is about keeping your code in a "green" state instead of writing a failing test first (red) and then make it pass (green), as we do with test-driven development. If we write a failing test, it'll just vanish, and we'll be brought back to the "green" state again.

Purpose of test-commit-revert

The main goal of this technique is to understand the code a bit better each time you add a test case. This will naturally increase the test coverage and unblock many refactorings that, otherwise, wouldn't be possible.

One of the advantages of test, commit, revert is that it's useful in many scenarios. We can use it with production code that has no tests at all or with code that's partially tested. If the tests fail, we just revert the change and try again.

How can we use it?

Kent Beck shows, in different articles and videos (linked at the end), that a good approach is using a script that runs after certain files in the project are saved.

This will depend heavily on the project you're trying to test. Something like the following script, which is executed every time we save files with a plugin in the editor, is a good start:

(rspec && git commit -am "WIP") || git reset --hard

If you're using Visual Studio Code, a good plugin to execute on every save is "runonsave". You can include the above command or a similar one for your project. In this case, the whole config file would be

{
  "folders": [{ "path": "." }],
  "settings": {
    "emeraldwalk.runonsave": {
      "commands": [
        {
          "match": "*.rb",
          "cmd": "cd ${workspaceRoot} && rspec && git commit -am WIP || git reset --hard"
        }
      ]
    }
  }
}

Remember that later, you can squash the commit with Git directly in the command line or when merging the PR if you're using Github:

This means we'll only get one commit in the main branch for all the commits we did on the branch we're working on. This diagram from Github explains it well:

Writing our first test with TCR

We'll use a simple example to illustrate the technique. We have a class that we know is working, but we need to modify it.

We could just make a change and deploy the changes to production. However, we want to be sure that we don't break anything in the process, which is always a good idea.

# worker.rb
class Worker
  def initialize(age, active_years, veteran)
    @age = age
    @active_years = active_years
    @veteran = veteran
  end

  def can_retire?
    return true if @age >= 67
    return true if @active_years >= 30
    return true if @age >= 60 && @active_years >= 25
    return true if @veteran && @active_years > 25

    false
  end
end

The first step would be to create a new file for the tests, so we can start adding them there. We've seen the first line in the can_retire? method with

  def can_retire?
    return true if @age >= 67
    ...
    ...
  end

Thus, we can test this case first:

# specs/worker_spec.rb
require_relative './../worker'

describe Worker do
  describe 'can_retire?' do
    it "should return true if age is higher than 67" do

    end
  end
end

Here's a quick tip: when you're working with test, commit, revert, every time you save, the latest changes will disappear if the tests fail. Therefore, we want to have as much code as possible to "set up" the test before actually writing and saving the line or lines with the assertion.

If we save the above file like that, we can then add a line for the test.

require_relative './../worker'

describe Worker do
  describe 'can_retire?' do
    it "should return true if age is higher than 67" do
      expect(Worker.new(70, 10, false).can_retire?).to be_true ## This line can disappear when we save now
    end
  end
end

When we save, if the new line doesn't vanish, we've done a good job; the test passes!

Adding more tests

Once we have our first test, we can keep adding more cases while taking into account false cases. After some work, we have something like this:

# frozen_string_literal: true

require_relative './../worker'

describe Worker do
  describe 'can_retire?' do
    it 'should return true if age is higher than 67' do
      expect(Worker.new(70, 10, false).can_retire?).to be true
    end

    it 'should return true if age is 67' do
      expect(Worker.new(67, 10, false).can_retire?).to be true
    end

    it 'should return true if age is less than 67' do
      expect(Worker.new(50, 10, false).can_retire?).to be false
    end

    it 'should return true if active years is higher than 30' do
      expect(Worker.new(60, 31, false).can_retire?).to be true
    end

    it 'should return true if active years is 30' do
      expect(Worker.new(60, 30, false).can_retire?).to be true
    end
  end
end

In every case, we write the "it" block first, save, and then add the assertion with expect(...).

As usual, we can add as many tests as possible, but it makes sense to avoid adding too many once we're relatively sure that everything is covered.

There are still a few cases to cover, so we should add them just for completeness.

Final tests

Here's the spec file in its final form. As you can see, we could still add more cases, but I think this is enough to illustrate the process of TCR.

# frozen_string_literal: true

require_relative './../worker'

describe Worker do
  describe 'can_retire?' do
    it 'should return true if age is higher than 67' do
      expect(Worker.new(70, 10, false).can_retire?).to be true
    end

    it 'should return true if age is 67' do
      expect(Worker.new(67, 10, false).can_retire?).to be true
    end

    it 'should return true if age is less than 67' do
      expect(Worker.new(50, 10, false).can_retire?).to be false
    end

    it 'should return true if active years is higher than 30' do
      expect(Worker.new(60, 31, false).can_retire?).to be true
    end

    it 'should return true if active years is 30' do
      expect(Worker.new(20, 30, false).can_retire?).to be true
    end

    it 'should return true if age is higher than 60 and active years is higher than 25' do
      expect(Worker.new(60, 30, false).can_retire?).to be true
    end

    it 'should return true if age is higher than 60 and active years is higher than 25' do
      expect(Worker.new(61, 30, false).can_retire?).to be true
    end

    it 'should return true if age is 60 and active years is higher than 25' do
      expect(Worker.new(60, 30, false).can_retire?).to be true
    end

    it 'should return true if age is higher than 60 and active years is 25' do
      expect(Worker.new(61, 25, false).can_retire?).to be true
    end

    it 'should return true if age is 60 and active years is 25' do
      expect(Worker.new(60, 25, false).can_retire?).to be true
    end

    it 'should return true if is veteran and active years is higher than 25' do
      expect(Worker.new(60, 25, false).can_retire?).to be true
    end
  end
end

Ways to refactor

If you've read this far, there's probably something that feels a bit off with the code. We have many "magical numbers" that should be extracted into constants, both in the test and in the Worker class.

We could also create private methods for each case in the main can_retire? public method.

I'll leave both potential refactorings as exercises for you. However, we have tests now, so if we make a mistake in any step, they will tell us.

Where do you go from here?

I encourage you to try test-commit-revert with your projects and production code. It's a very cheap experiment because you don't need any fancy continuous integration in an external server or a dependency with a new library. All you need is a way to execute a command every time you save certain files on your computer.

It'll also give you a "gaming" experience when adding tests, which is always fun and interesting. Additionally, the discipline of having failing tests removed from your editor (a safety measure that kicks in whenever tests fail) will give you an extra safety net by confirming that the tests you're pushing to the repository are actually passing.

I hope you find this new technique useful when dealing with legacy code. I've used multiple times in the last few months, and it's always been a pleasure.

Tips for upgrading Python/Django versions in existing apps

2023-07-20T00:00:00+00:00

Python is a robust and powerful programming language. In addition to machine learning, Python can be used for tasks such as web scraping, image processing, scientific computing, and much more. A framework such as Django, which is built on top of Python, enables you to build beautiful web applications—top websites such as Dropbox, Instagram, and YouTube use Django.

However, as you create applications and release them to consumers, upgrading to the latest Python version becomes essential to keep pace with updates and new features. For instance, Python 3.11 was released in October 2022, sporting various bug fixes. Before that, there was Python 3.10, 3.9, 3.8, and others. There are also numerous third-party libraries that you should regularly watch out for.

Incorporating these updates into our applications can be beneficial, as doing so can enhance the security and reliability. However, doing this incorrectly could also break your application.

Why you should be upgrading your Python version

Upgrading your Python and Django applications to the latest Python version is important for several reasons.

New Python versions come with additional features and improvements. Newer Django versions can help reduce boilerplate code, enabling you to develop and push products to the market much faster. They can also help you learn new ways of adding functionalities to your application that can be more fun and easier to implement.
New Python versions can help with bug fixes in your code. Apart from enabling your application to behave as expected, eliminating bugs also streamlines the software development process, meaning that you'll be less frustrated. A Python upgrade can improve your app's stability during production.
Upgrading your application also makes it easier to maintain your codebase. You can quickly incorporate changes in your project without major downtimes.
Ensuring you're using the latest Python version and Django version also improves security. Hackers are always looking for new ways to infiltrate systems, steal data, install malicious files and viruses, and just wreak havoc. Upgrading your application to use the latest Python version or Django ensures that you have the latest security updates.

Now that we understand why upgrading applications is necessary, let's jump into the action itself.

Things to know before updating

Before updating the Python version, you should read the changes in the newest Python release. Go through the official documentation, particularly the release notes. Note that with each new version, Django releases accompanying documentation, which is quite helpful when upgrading applications.

Next, look at the functions, objects, and other items deprecated in the latest Python version. Consider the deadline or timeline in which these deprecation changes are set to come into effect. Understanding the deprecation timeline allows you to better plan your upgrade process, including the prioritization of certain tasks over others.

You should also keep an eye on backwards compatibility. Remember that some things that work in your existing application may fail when you upgrade to a new Python version. This is why it's recommended to test things first before pushing to production. Whenever an upgrade causes your app to break, you can roll back to the previous Python version as you figure out the next steps.

How to update Python/Django apps

In this section, we will learn how to upgrade Python and Django in a simple Django Movie API to use a newer Python version. You can download the project's code from this GitHub repository.

Check Django and other library versions

Once you've downloaded the Movie API project and finished setting it up on your computer, the first step is to check the versions of the dependencies that the project uses.

To do this, launch the project in your preferred code editor and open the requirements.txt file. All dependencies used by the project are listed in this file, as follows.

asgiref==3.3.1
Django==3.1.8
django-filter==2.4.0
djangorestframework==3.12.2
djangorestframework-simplejwt==4.6.0
pytz==2021.1
sqlparse==0.4.1

Since we now know the versions in use (shown above), the next step is to determine the current official version from the documentation. For instance, the latest official Django version is 4.2.1; our application uses an older version (3.1.8), so there's a need to upgrade.

Activate local debugging

Trying to update things in production could cause them to break and lead to poor user experience and other negative consequences. You should test your applications locally and ensure that everything is working before pushing them to production.

You can activate local debugging by setting the debug option in the settings.py file to True.

# settings.py
import os

# Build paths inside the project like this: os.path.join(BASE_DIR, …)
BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

# Quick-start development settings - unsuitable for production
# See https://docs.djangoproject.com/en/2.0/howto/deployment/checklist/wa

# SECURITY WARNING: Don’t run with debug turned on in production!
DEBUG = True  # Set debug to true

ALLOWED_HOSTS = []

Run Django checks with python -Wall manage.py check

Before starting the upgrade, we'll need to run several checks to determine if there are any deprecation warnings in our project.

Deprecation warnings show that certain features will stop working at some point simply because they have been replaced by better alternatives.

You can check for any warnings using the following command:

python -Wa manage.py test

Install new dependencies

Now that we have enabled local debugging and identified any deprecation warnings in our project, it's time to install new dependencies in our project.

To get the latest Django version, we use the following command.

python -m pip install -U Django

When you run the above command, the following output should appear in your terminal. We have now successfully updated Django to ver 4.2.1, asgiref to ver 3.6.0, and tzdata to ver 2023.3.

Requirement already satisfied: Django in c:\users\wanjamike\appdata\local\programs\python\python310\lib\site-packages (3.1.8)
Collecting Django
  Downloading Django-4.2.1-py3-none-any.whl (8.0 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 8.0/8.0 MB 43.5 kB/s eta 0:00:00
Requirement already satisfied: sqlparse>=0.3.1 in c:\users\wanjamike\appdata\local\programs\python\python310\lib\site-packages (from Django) (0.4.1)
Collecting tzdata
  Using cached tzdata-2023.3-py2.py3-none-any.whl (341 kB)
Collecting asgiref<4,>=3.6.0
  Using cached asgiref-3.6.0-py3-none-any.whl (23 kB)
Installing collected packages: tzdata, asgiref, Django
  Attempting uninstall: asgiref
    Found existing installation: asgiref 3.3.1
    Uninstalling asgiref-3.3.1:
      Successfully uninstalled asgiref-3.3.1
  Attempting to uninstall: Django
    Found existing installation: Django 3.1.8
    Uninstalling Django-3.1.8:
      Successfully uninstalled Django-3.1.8
Successfully installed Django-4.2.1 asgiref-3.6.0 tzdata-2023.3

We can update the remaining dependencies in our project using the following command:

python -m pip install -U django-filter djangorestframework djangorestframework-simplejwt pytz sqlparse

Expected output:

Successfully installed django-filter-23.2 djangorestframework-3.14.0 djangorestframework-simplejwt-5.2.2 pytz-2023.3 sqlparse-0.4.4

Let's generate a new requirements.txt file and double-check that we have the latest libraries in our project.

pip freeze > requirements.txt

When you open the requirements.txt, you should find all the latest dependencies, as shown below:

asgiref==3.6.0
Django==4.2.1
django-filter==23.2
djangorestframework==3.14.0
djangorestframework-simplejwt==5.2.2
pytz==2023.3
sqlparse==0.4.4
tzdata==2023.3

Check methods and functions

In most software updates, developers will try to change how certain functions or components work to improve performance, efficiency, memory usage, or convenience. Rather than fighting such changes, consider embracing and integrating them into your application to realize their benefits.

Note that while this may be a time-consuming step, the benefits are worth it. You should go through the official documentation to understand new changes and learn how you can integrate them into your application.

Let's review some of the changes in Django 4.2 that can help you in future upgrades.

First, support for MariaDB 10.3, MySQL 5.7, and PostgreSQL 11 databases was dropped. If your application was using any of these database versions, consider upgrading. Make sure to back up your data before upgrading to avoid service disruptions.

Second, Django 4.2 changed how we do data indexing. In the past, we indexed data using the statement below:

index_together = [["rank", "name"]]

But now we must call the Index method from the models class, as demonstrated below.

indexes = [models.Index(fields=["rank", "name"])]

Third, the length_is template filter is now deprecated and has instead been replaced by the traditional == operator.

Don't do this:

{% if value|length_is:4 %}…{% endif %}
{{ value|length_is:4 }}

Do this:

{% if value|length == 4 %}…{% endif %}
{% if value|length == 4 %}True{% else %}False{% endif %}

Updating Python is important

Updates are a normal thing during software development. Therefore, it's best to learn how to update your app's Python version and integrate changes in our applications. Apart from improved security, software updates allow us to deal with bugs and ensure that our code is maintainable.

When upgrading to a new version of Python, make sure to test things out in your local environment before pushing them to production. We don't want things to break and cause a poor user experience.

Errors in Python: types, causes, and examples

2026-04-27T00:00:00+00:00

Errors in Python are issues in a program that cause incorrect results or prevent proper execution. Some Python errors are loud and obvious, and your code barely gets started before it throws an error that tells you exactly what went wrong. Other errors are more subtle, allowing your Python program to run without complaints while silently producing incorrect results that only become apparent later. These differences become clearer when you group errors in Python based on how they occur and how they impact execution.

For example, syntax errors get caught before the code even runs, and runtime errors blow up mid-execution. System-level errors have nothing to do with your code—and they still stop execution—while logical errors don’t stop execution but produce incorrect results. Understanding the different types of errors and learning how to avoid them is essential for writing reliable and robust code. Let's look at the different types of errors in Python, their causes, and how to avoid them.

Different types of errors in Python

We can broadly categorize Python errors into four types, as shown in the following image:

Syntax errors: Syntax errors in Python occur due to invalid syntax, incorrect indentation, or typos. These errors are detected before the program is executed, while the Python interpreter parses the code.
Runtime errors: In Python, runtime errors occur during execution when the program encounters an invalid operation.
System-level errors: System-level errors in Python are raised by the runtime environment or the operating system due to issues such as memory overflow or interruptions.
Logical errors: Logical errors occur when the program's logic is incorrect, even though the code runs without errors, producing incorrect results.

Let's discuss all these Python error types one by one in detail with examples, starting with syntax errors.

Syntax errors in Python

Syntax errors are the errors caused by invalid code structure, typos, incorrect indentation, etc. For example, an if block is defined in Python using the if keyword, a boolean condition, and the : character. If we skip : while writing an if block in Python, the code runs into SyntaxError with the error message SyntaxError: expected ':', as shown in the following example:

if x > 10
    print("Honeybadger")

This code gives the following error message:

  File "/path/to/code.py", line 1
    if x > 10
             ^
SyntaxError: expected ':

Syntax errors occur when the interpreter cannot parse the code because it violates Python’s grammar rules. Let's discuss some of the common syntax errors in Python.

Indentation errors in Python

Python uses spaces and tabs for code indentation. The code will run into IndentationError if a code block doesn't have correct indentation. For example, defining an if block requires us to indent the lines in the if block to the right by two/four spaces. If we don't indent the lines in the if block, the code runs into IndentationError with the error message IndentationError: expected an indented block after 'if' statement on line x.

if x > 10:
print("Honeybadger")

The unindented if block gives the following error:

  File "/path/to/code.py", line 2
    print("Honeybadger")
    ^
IndentationError: expected an indented block after 'if' statement on line 1

Similarly, we need to indent the code block inside a function definition. Not doing so gives us an IndentationError with the message IndentationError: expected an indented block after function definition on line x, as shown below:

def say_hello(name):
print(f"Hi {name}, you are at Honeybadger")

In this code, the print statement inside the say_hello() function isn't indented to the right. Hence, the code gives the following error:

  File "/path/to/code.py", line 2
    print(f"Hi {name}, you are at Honeybadger")
    ^
IndentationError: expected an indented block after function definition on line 1

When you indent a code block, it is important to keep the indentation the same for each statement in the code block. Otherwise, the program runs into IndentationError. For example, if you indent the first statement of a code block by four spaces and the second statement by two spaces, the program will run into IndentationError with the error message IndentationError: unindent does not match any outer indentation level, as shown in the following example:

def say_hello(name):
    print(f"Hi {name}, you are at Honeybadger")
  print("Great seeing you here.")

Output:

  File "/path/to/code.py", line 3
    print("Great seeing you here.")
                                   ^
IndentationError: unindent does not match any outer indentation level

Similarly, if you indent the first statement in a code block by two spaces and the second statement by four spaces, the program will run into IndentationError with the message IndentationError: unexpected indent, as shown below:

def say_hello(name):
  print(f"Hi {name}, you are at Honeybadger")
    print("Great seeing you here.")

Output:

  File "/path/to/code.py", line 3
    print("Great seeing you here.")
IndentationError: unexpected indent

Tab error

TabError is a specific indentation error caused by mixing tabs and spaces to indent code blocks. For instance, you can indent a statement by the same distance using four spaces or one tab. Visually, it looks the same. However, if you indent a statement in a code block using a tab and another using four spaces, the program will run into TabError with the error message TabError: inconsistent use of tabs and spaces in indentation, as shown in the following example:

def say_hello(name):
    print(f"Hi {name}, you are at Honeybadger") # Indentation using Tab
    print("Great seeing you here.")  # Indentation using four spaces

Output:

  File "/path/to/code.py", line 3
    print("Great seeing you here.")  # Indentation using four spaces
TabError: inconsistent use of tabs and spaces in indentation

Python 3 explicitly disallows mixing tabs and spaces for indentation in a way that makes the meaning ambiguous, and you should always avoid it.

Unclosed strings/ brackets/ parentheses

A Python program runs into a SyntaxError if you don't close a string, parentheses, or a bracket. For example, if you don't close a string, the program runs into SyntaxError with the message SyntaxError: unterminated string literal.

if x > 10:
    print("Honeybadger)

In this code, the closing " is missing in the "Honeybadger string. Due to this, the program runs into SyntaxError, as shown below:

  File "/path/to/code.py", line 2
    print("Honeybadger)
          ^
SyntaxError: unterminated string literal (detected at line 2)

Similarly, if we forget the closing parenthesis while calling a function or defining a tuple, the program runs into SyntaxError with the message SyntaxError: '(' was never closed, as shown below:

print("Honeybadger"

Output:

  File "/path/to/code.py", line 1
    print("Honeybadger"
         ^
SyntaxError: '(' was never closed

Just like parentheses, if we miss the closing bracket while defining a list, the program runs into SyntaxError with the message SyntaxError: '[' was never closed, as shown below:

my_list = [1, 2, 3

Output:

  File "/path/to/code.py", line 1
    my_list = [1, 2, 3
              ^
SyntaxError: '[' was never closed

Invalid assignment errors

Invalid assignment errors are mostly caused by assigning values to literals or function calls. For example, if we assign the value "Honeybadger" to a string literal "name", the program throws a SyntaxError with the message SyntaxError: cannot assign to literal here. Maybe you meant '==' instead of '='?, as shown below:

"name" = "Honeybadger"

Output:

  File "/path/to/code.py", line 1
    "name" = "Honeybadger"
    ^^^^^^
SyntaxError: cannot assign to literal here. Maybe you meant '==' instead of '='?

Similarly, if we assign a value to a Python keyword, the program runs into a SyntaxError. For example, assigning the value Honeybadger to a variable class results in a SyntaxError with the message SyntaxError: invalid syntax, as class is a Python keyword.

class = "Honeybadger"

Output:

  File "/path/to/code.py", line 1
    class = "Honeybadger"
          ^
SyntaxError: invalid syntax

An assignment error also occurs when we miss a = character while comparing values using the equality operator. For example, if we use = instead of == to compare two values, the program runs into SyntaxError with the error message SyntaxError: invalid syntax. Maybe you meant '==' or ':=' instead of '='?, as shown below:

name = "Honeybadger"
input_string = "Honeybadger"
if name = input_string:
  print(name)

Output:

  File "/path/to/code.py", line 3
    if name = input_string:
       ^^^^^^^^^^^^^^^^^^^
SyntaxError: invalid syntax. Maybe you meant '==' or ':=' instead of '='?

How to avoid syntax errors in Python?

Syntax errors occur due to incorrect indentation, mismatched delimiters, missing punctuation, invalid variable names, or incorrect operators. You can avoid syntax errors using the following best practices:

Always add the required colon : after block statements like if, for, while, def, and class.
Avoid using reserved keywords such as class, for, if, or return as variable names.
Always close all the parentheses (), brackets [], and braces {}.
Close all string literals with matching quotation marks ' or ".
Follow Python syntax rules and ensure statements are written in the correct format.
Maintain consistent indentation, preferably using 4 spaces per indentation level, and do not mix tabs and spaces for indentation.

In addition to the above practices, you can use IDEs or code editors such as PyCharm, Spyder, or VS Code that provide syntax highlighting and linting to detect syntax errors early.

Runtime errors in Python

Runtime errors occur in a Python program after it passes the syntax check and starts executing, when something goes wrong. Examples of runtime errors in Python include ZeroDivisionError, NameError, TypeError, and ValueError. Let’s discuss the different runtime errors, their causes, and ways to avoid them.

Zero division error

The ZeroDivisionError exception is one of the most common arithmetic errors that occurs if the denominator of a division operation is zero.

x = 10 / 0

Here, we are dividing 10 by 0. Hence, the program runs into ZeroDivisionError with the error message ZeroDivisionError: division by zero:

Traceback (most recent call last):
  File "/path/to/code.py", line 1, in <module>
    x = 10 / 0
ZeroDivisionError: division by zero

Name error

The NameError exception is a runtime error that occurs when a variable is referenced before assignment.

y = x / 10

In this code, we tried to divide x by 10 without defining x or assigning it a value. Hence, the variable name x isn't present in the scope of the program, and the program runs into a NameError exception with the error message NameError: name 'x' is not defined.

Traceback (most recent call last):
  File "/path/to/code.py", line 1, in <module>
    y = x / 10
NameError: name 'x' is not defined

The NameError exception also occurs if you use a variable first and define it later in the program. For example, consider the following code:

print(greeting)
greeting = "Hi, you are at Honeybadger"

Here, we have referenced the variable greeting and later assigned it a value. Hence, the program throws a NameError exception.

Traceback (most recent call last):
  File "/path/to/code.py", line 1, in <module>
    print(greeting)
NameError: name 'greeting' is not defined

Unbound local error

The UnboundLocalError exception occurs when a local variable is referenced before assignment, in a function or method. For instance, consider the following code:

def say_hello():
    print(greeting)
    greeting = "Hi, you are at Honeybadger"
    
say_hello()

In this code, we have referenced the variable greeting before assigning it a value in the say_hello() function. When we call the say_hello() function, the program raises the UnboundLocalError exception with the message UnboundLocalError: local variable 'greeting' referenced before assignment.

Traceback (most recent call last):
  File "/path/to/code.py", line 5, in <module>
    say_hello()
  File "/path/to/code.py", line 2, in say_hello
    print(greeting)
UnboundLocalError: local variable 'greeting' referenced before assignment

Here, if we hadn't assigned any value to the variable after the print statement, the program would have run into a NameError exception, as shown below:

def say_hello():
    print(greeting)
    print("Hi, you are at Honeybadger")

say_hello()

Output:

Traceback (most recent call last):
  File "/path/to/code.py", line 5, in <module>
    say_hello()
  File "/path/to/code.py", line 2, in say_hello
    print(greeting)
NameError: name 'greeting' is not defined

Type error

The TypeError exceptions in Python occur when an operation is applied to a value or variable of an incompatible data type. For example, adding an integer and a string results in a TypeError exception with the error message TypeError: unsupported operand type(s) for +: 'int' and 'str', as shown below:

x = 10 + "Honeybadger"

Output:

Traceback (most recent call last):
  File "/path/to/code.py", line 1, in <module>
    x = 10 + "Honeybadger"
TypeError: unsupported operand type(s) for +: 'int' and 'str'

Similarly, calling a non-callable object or iterating on a non-iterable object also results in a TypeError exception, as shown below:

name = "Honeybadger"
name()

Output:

Traceback (most recent call last):
  File "/path/to/code.py", line 2, in <module>
    name()
TypeError: 'str' object is not callable

In this code, we defined a string variable name and tried to use it as a function in the second line. Hence, the program throws a TypeError exception with the message TypeError: 'str' object is not callable.

Value error

The ValueError exception occurs in a Python program when we use an input or a variable with the correct data type but an inappropriate value. For instance, the int() function converts a string to an integer. If the string passed to the int() function cannot be converted into an integer, the program runs into a ValueError exception, as shown in the following example:

x = int("10")
y = x + int("Honeybadger")
print(y)

In this code, the statement x=int("10") executes successfully because "10" is successfully converted into an integer. However, the string "Honeybadger" cannot be converted to an integer. Hence, the second line of the code raises a ValueError exception with the error message ValueError: invalid literal for int() with base 10: 'Honeybadger', as follows:

Traceback (most recent call last):
  File "/path/to/code.py", line 2, in <module>
    y = x + int("Honeybadger")
ValueError: invalid literal for int() with base 10: 'Honeybadger'

Similarly, square roots aren't defined for negative numbers. Hence, passing a negative number to the math.sqrt() function results in a ValueError exception due to an inappropriate value.

import math
x = math.sqrt(-10)

Output:

Traceback (most recent call last):
  File "/path/to/code.py", line 2, in <module>
    x = math.sqrt(-10)
ValueError: math domain error

In this code, -10 has the correct integer data type that the sqrt() function requires. However, it is an invalid value, and we get a ValueError exception with the message ValueError: math domain error.

Index error

The IndexError exception occurs in a Python program when we try to access an element at an index that doesn't exist in an iterable object like a string, list, or tuple. For example, if a list has six elements and we try to access the element at index 6 (the seventh element), the program runs into an IndexError exception with the message IndexError: list index out of range, as shown below:

my_list = [1, 2, 3, 4, 5, 6]
print(my_list[6])

Output:

Traceback (most recent call last):
  File "/path/to/code.py", line 2, in <module>
    print(my_list[6])
IndexError: list index out of range

Similarly, if we try to access an element at a non-existent index in a string, the program runs into an IndexError exception with the message IndexError: string index out of range, as shown in the following code:

name = "Honeybadger"
print(name[20])

In this code, we tried to access the character at index 20 in the string. However, the string is eleven characters long. Hence, the program raises an IndexError exception.

Traceback (most recent call last):
  File "/path/to/code.py", line 2, in <module>
    print(name[20])
IndexError: string index out of range

Key error

KeyError exceptions occur when we try to access a non-existent key in a Python dictionary. For instance, the dictionary in the following code has keys "a", "b", "c", and "d". When we try to fetch a value with the key "e", the program runs into a KeyError exception, as shown below:

my_dict = {"a": 1, "b": 2, "c": 3, "d": 4}
print(my_dict["e"])

Output:

Traceback (most recent call last):
  File "/path/to/code.py", line 2, in <module>
    print(my_dict["e"])
KeyError: 'e'

Module not found error

The ModuleNotFoundError occurs when we try to import a module that hasn't already been installed or downloaded to the Python module search path.

For example, suppose you want to use Honeybadger for error monitoring in a Python application. However, if you don't install honeybadger using pip and start directly by importing the honeybadger module into your code, the program will run into ModuleNotFoundError with the message ModuleNotFoundError: No module named 'honeybadger'.

import honeybadger
print("You are at Honeybadger")

Output:

Traceback (most recent call last):
  File "/path/to/code.py", line 1, in <module>
    import honeybadger
ModuleNotFoundError: No module named 'honeybadger'

ModuleNotFoundError is a specific type of ImportError that occurs when Python cannot find the module file being imported.

Import errors in Python

ImportError is a more general exception that can occur for various reasons during the import process, even when the module file exists but cannot be imported successfully due to dependency requirements or other issues. If a module exists but raises an exception while being imported, Python raises ImportError.

For instance, if we try to import a non-existent function from the honeybadger module after installing it, the program runs into an ImportError exception.

from honeybadger import nonexistingfunction

Here, we tried to import nonexistingfunction from the honeybadger module. Hence, the program raises an ImportError with the message ImportError: cannot import name 'nonexistingfunction' from 'honeybadger':

Traceback (most recent call last):
  File "/path/to/code.py", line 1, in <module>
    from honeybadger import nonexistingfunction
ImportError: cannot import name 'nonexistingfunction' from 'honeybadger'

Attribute error

In Python, every object has a set of associated attributes, i.e., field names and methods. For example, a Python list has the append() method that we use to add new values to a list. However, a tuple, an integer, a string, or a floating-point value doesn't have the append() method. Hence, if we invoke the append() method on a tuple, the program raises an AttributeError exception.

my_tuple = (1, 2, 3, 4, 5)
my_tuple.append(6)

In this code, we have used the append() method on a tuple. Hence, the program throws an AttributeError exception with the message AttributeError: 'tuple' object has no attribute 'append'.

Traceback (most recent call last):
  File "/path/to/code.py", line 2, in <module>
    my_tuple.append(6)
AttributeError: 'tuple' object has no attribute 'append'

Memory error

MemoryError in Python is a built-in exception that occurs when a program fails to allocate memory for a Python object. It usually occurs when handling extremely large datasets, constructing oversized data structures, or running inefficient code that leads to excessive memory consumption or memory leaks.

For example, creating a huge list having ten billion elements can lead to a MemoryError exception, as shown below:

my_list = [10] * (10**10)

Output:

Traceback (most recent call last):
  File "/path/to/code.py", line 1, in <module>
    my_list = [10] * (10**10)
MemoryError

While MemoryError is a runtime error, it often indicates that the program has exceeded a system limit, such as running out of RAM or exceeding the operating system's address space limit.

Recursion error

A recursion error is a runtime error that occurs when the recursion depth exceeds the limit of 1000 recursive calls. The RecursionError exception occurs if we forget to add a base case or a terminating condition while defining a recursive function. For instance, consider the following increment_till_hundred() function:

def increment_till_hundred(x):
    x += 1
    print(x)
    increment_till_hundred(x)
    
increment_till_hundred(80)

In the increment_till_hundred() function, we haven't defined any termination condition if the value of x reaches 100. Hence, the function keeps making the recursive call, exceeding the limit of 1000 recursive calls, and the program runs into RecursionError with the message RecursionError: maximum recursion depth exceeded while calling a Python object, as shown below:

Traceback (most recent call last):
  File "/path/to/code.py", line 6, in <module>
    increment_till_hundred(80)
  File "/path/to/code.py", line 4, in increment_till_hundred
    increment_till_hundred(x)
  [Previous line repeated 994 more times]
  File "/path/to/code.py", line 3, in increment_till_hundred
    print(x)
RecursionError: maximum recursion depth exceeded while calling a Python object

How to avoid runtime errors in Python?

Runtime errors are difficult to detect because they do not prevent the program from starting execution, unlike syntax errors. Hence, the program runs normally at first, and the error may only appear later when the line containing the problematic code is executed. To avoid runtime errors, you can use the following best practices:

Always validate the input data before processing to ensure it has the correct data type, format, and range.
Always implement exception handling in your Python code to catch and handle runtime errors gracefully, rather than crashing the program.
Perform type checking using the isinstance() function or convert the data type of values using int(), float(), and str() functions before applying operations on values.
Maintain a properly configured runtime environment, ensuring all required modules, dependencies, and system libraries are correctly installed.
Test the code with different edge cases to identify potential runtime failures early.

Apart from the above practices, always write modular, well-structured code so you can easily isolate and debug errors if they occur.

System-level errors in Python

System-level errors occur in a Python program when it encounters issues such as I/O failures, memory overflows, or connection errors. All the system-level errors in Python are raised using the OSError exception or its subclasses. Let's discuss the different system-level errors in Python and how to avoid them.

File not found errors in Python

The FileNotFoundError exception occurs when we try to read a non-existent file. For example, suppose that we want to read a text file named sampletextfile.txt using the open() function. If the file doesn't exist, the program runs into FileNotFoundError with the message FileNotFoundError: [Errno 2] No such file or directory: 'sampletextfile.txt', as shown below:

file = open("sampletextfile.txt", "r")

Output:

Traceback (most recent call last):
  File "/path/to/code.py", line 1, in <module>
    file = open("sampletextfile.txt", "r")
FileNotFoundError: [Errno 2] No such file or directory: 'sampletextfile.txt'

Permission error

If a file exists and we don't have permission to read or modify it, the program raises a PermissionError exception. For example, suppose that we have a file samplefile.txt with only read access, as shown in the image:

Now, if we try to open the file in append mode and modify it, the program raises a PermissionError exception with the message PermissionError: [Errno 13] Permission denied: 'samplefile.txt'. However, opening the file in read mode will not cause any issues, as we have permission to read it.

file = open("samplefile.txt", "a")

Output:

Traceback (most recent call last):
  File "/path/to/code.py", line 1, in <module>
    file = open("samplefile.txt", "a")
PermissionError: [Errno 13] Permission denied: 'samplefile.txt'

Is a directory error

We can open files using the open() function in Python. However, if you try to open a directory using the open() function, the program raises the IsADirectoryError exception.

file = open("/path/to/directory", "r")

In this code, /path/to is a directory. Hence, the program throws an IsADirectoryError exception with the message IsADirectoryError: [Errno 21] Is a directory

Traceback (most recent call last):
  File "/path/to/code.py", line 1, in <module>
    file = open("/path/to/directory", "r")
IsADirectoryError: [Errno 21] Is a directory: '/path/to/directory'

Connection error

In Python, the ConnectionError exception occurs due to network issues such as a lost internet connection, DNS errors, server downtime, or when the client fails to establish a connection to the server within a specified time limit. For instance, using the requests module to make an API call without connecting the system to the network results in the ConnectionError exception, as shown below:

import requests
response = requests.get('https://jsonplaceholder.typicode.com/todos/1')

Output:

Traceback (most recent call last):
  File "/path/to/code.py", line 4, in <module>
    response = requests.get('https://jsonplaceholder.typicode.com/todos/1')
  .
  .
  File "/home/user/.local/lib/python3.10/site-packages/requests/adapters.py", line 700, in send
    raise ConnectionError(e, request=request)
requests.exceptions.ConnectionError: HTTPSConnectionPool(host='jsonplaceholder.typicode.com', port=443): Max retries exceeded with url: /todos/1 (Caused by NameResolutionError("<urllib3.connection.HTTPSConnection object at 0x7400d45a6c80>: Failed to resolve 'jsonplaceholder.typicode.com' ([Errno -3] Temporary failure in name resolution)"))

Connection refused error

The ConnectionRefusedError is a subclass of ConnectionError, which specifically indicates that a connection attempt was explicitly refused by the remote host. It occurs due to an incorrect IP address or port number, firewall blocking, or if the server is not running or has reached its maximum capacity for pending connections. For example, consider the following code:

import socket
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.connect(("localhost", 9999))

We have not run any application on port 9999. Hence, when the Python program tries to connect to the port, the program runs into ConnectionRefusedError with the message ConnectionRefusedError: [Errno 111] Connection refused, as shown below:

Traceback (most recent call last):
  File "/path/to/code.py", line 3, in <module>
    s.connect(("localhost", 9999))
ConnectionRefusedError: [Errno 111] Connection refused

How to avoid system-level errors in Python?

System-level errors in Python are often caused by missing files, insufficient permissions, memory limitations, or network failures. Although we cannot always prevent them, we can minimize system-level errors through careful resource management, validation checks, and proper exception handling. You can use the following practices to avoid system-level errors in Python.

Always check whether files and directories exist before performing file operations.
Check access permissions to ensure the program has the required read, write, and execute permissions for files and directories.
Manage memory efficiently by avoiding extremely large data structures and using generators or batch processing for large datasets.
Use context managers (with statement) when working with files, sockets, or other resources to ensure they are automatically closed after use.
Ensure required system resources, such as disk space, memory, and network connectivity, are available.

The best way to avoid system-level errors is to anticipate potential failures and write defensive code that validates resources and handles exceptions gracefully, since these are mostly caused by environmental or resource constraints.

Logical errors in Python

A logical or semantic error in Python occurs when a program runs without crashing or raising exceptions but produces incorrect or unintended results due to flawed code logic. Unlike syntax errors or runtime errors, Python cannot detect logical errors automatically because the code is syntactically valid and executes successfully. Logical errors occur due to incorrect algorithms, wrong conditions, faulty calculations, or mistaken assumptions in program logic.

For example, consider that you are writing a Python application to determine the voting eligibility of a person based on their age. It is given that a person aged 18 or older is eligible to vote. Now consider the following code:

if age > 18:
    print("Eligible to vote")
else:
    print("Not eligible")

This code executes successfully. But it produces incorrect output for people aged 18 due to an incorrect condition. Hence, we should have used the >= operator instead of the > operator in the if block.

Logical errors can also occur due to incorrect use of logical operators. For example, suppose we need to determine whether a person is of working age, defined as 18 to 60 years old, inclusive. Now, consider the following code:

age = 70
if age >= 18 or age <= 60:
    print("Working age")

Output:

Working age

This code prints "Working age" even if the person is over 60 years old because the first condition is True, and the or operator evaluates to True if either operand is True. Hence, we should have used the and operator rather than the or operator to get the correct output.

Logical errors are much harder to detect because the Python application does not run into exceptions. The output may appear reasonable but will still be incorrect. We can detect and avoid logical errors through unit testing, debugging, and code review, ensuring there are no flaws in the code.

Know your errors before your users do

No matter how experienced you get, errors in an application never fully disappear. What changes is how quickly you recognize them, how calmly you respond, and how efficiently you solve the errors. In this article, we discussed the different syntax errors, runtime errors, system-level errors, and logical errors in Python and how to avoid them. While we cannot eliminate errors entirely, we can significantly reduce them by following error-handling best practices.

It is important to recognize that not every error can be caught during development. Certain bugs only emerge in production, often triggered by specific user actions in unpredictable sequences that may not be covered by testing. When this occurs, users may encounter an error before the development team discovers it. This is where error tracking and application monitoring become essential.

Honeybadger provides error tracking, logging, uptime monitoring, and performance monitoring under one roof. Sign up for a free trial of Honeybadger to monitor your applications by combining error tracking, logging, and uptime monitoring, so you always know the state of your application and can catch errors before they snowball.

Honeybadger Developer Blog

A comprehensive guide to Fly.io logging

How does Fly.io logging work?

Basic way to access logs on Fly.io

Building a FastAPI application that generates logs

Containerizing the application

Creating a Fly.io application

Viewing logs from the Fly.io dashboard

Shipping Fly.io logs to Honeybadger Insights

More on Honeybadger Insights

August 2026 product update: hosted MCP and more

MCP gets OAuth, and self-hosting gets more flexible

EU support is also here

What to do with your MCP

Also shipped this month

Comprehensive guide to working with Python markdown

Prerequisites

Setting Up a Project

Converting Markdown to HTML in Python

Converting a Markdown File to HTML in Python

Converting HTML to Markdown in Python

Converting an HTML File to Markdown in Python

Using Front Matter for Python markdown

Updating Markdown Front Matter in Python

Using Python Markdown Extensions

where do you go from here?

Starlette vs FastAPI: what FastAPI actually adds

What Starlette and FastAPI actually are

Starlette vs FastAPI: core differences

Performance and async capabilities

Middleware: same stack, same tools

WebSocket support

Data validation and serialization

Automatic documentation generation

When to use Starlette directly

How the layers fit together

Starlette vs FastAPI: where the layers end

How a status page can show a site at its best (and 10 examples)

Why is it important to have a public status page?

What should a strong status page include?

10 great status page examples

Wistia

Okta

Flare

Deno

Harvard

Graphite

PagerTree

Docker

Vimeo

RubyGems

Issues to look out for when creating a status page

Is your status page easy to manage?

Does your status page integrate well with monitoring tools?

Is your status page showing users what they want?

How to create the best status page in Honeybadger

Creating a status page is easier than you think with Honeybadger

Next.js error handling: a practical guide

Handling expected errors

Server Actions

Server Components

Handling 404s with notFound()

Handling uncaught exceptions

The error.tsx convention

Nested error boundaries

global-error.tsx

Event handler errors

Capturing and reporting Next.js errors with Honeybadger

Installation and setup

Wrapping your app with the error boundary

Manual error reporting

Next.js error handling best practices

Next.js vs React: What’s the difference and which should you use?

What is React?

The component and hook model

What React deliberately leaves out

What is Next.js and how does it extend React?

The App Router and Server Components

Client Components and the 'use client' boundary

Key differences

Handling 404s with `notFound()`