Python SDK

import os
from flask import Flask
from bugstack import init_bugstack

app = Flask(__name__)

# Initialize bugstack
init_bugstack(api_key=os.environ['BUGSTACK_API_KEY'])

@app.route('/')
def hello():
    return 'Hello World'

# bugstack automatically captures unhandled exceptions

import os
from fastapi import FastAPI
from bugstack import init_bugstack

app = FastAPI()

# Initialize bugstack
init_bugstack(api_key=os.environ['BUGSTACK_API_KEY'])

@app.get('/')
async def root():
    return {'message': 'Hello World'}

# bugstack automatically captures unhandled exceptions

# settings.py
import os
from bugstack import init_bugstack

# Initialize bugstack in your Django settings
init_bugstack(api_key=os.environ['BUGSTACK_API_KEY'])

# Add bugstack middleware
MIDDLEWARE = [
    'bugstack.django.BugStackMiddleware',
    # ... your other middleware
]

The bugstack Python SDK registers a sys.excepthook replacement and framework-specific error handlers. After bugstack.init() runs, it captures any unhandled exception raised inside Flask view functions, FastAPI path operations, Django views and middleware, and Celery task bodies. Every event includes the full traceback, request context (path, method, query string), and any user ID your framework exposes via its session middleware.

Reporting is non-blocking. The SDK enqueues events onto a background thread and flushes via a small HTTP client, so a slow or unreachable bugstack endpoint never stalls a user request. Queue size is bounded; in the rare event of sustained backpressure, the oldest events are dropped rather than leaking memory.

Flask integration is automatic — the SDK registers an app.errorhandler(Exception) as soon as you call bugstack.init() before your first request. FastAPI uses an exception handler registered against Exception, capturing errors from sync and async path operations alike. Django's adapter installs a middleware (add bugstack.django.Middleware to MIDDLEWARE) that records exceptions before Django's own error-page rendering.

For Celery workers, the SDK subscribes to the task_failure signal, so retried and failed tasks show up in the dashboard with the same fingerprint across replays. Background-job libraries like RQ and Dramatiq are supported via a small wrapper around their error callbacks.

• api_key (required) — read from BUGSTACK_API_KEY env var. Never hard-code.
• environment (optional) — string tag (production, staging, etc). Surfaces as a filter in the dashboard.
• release (optional) — git SHA or version string, attached to every event for regression tracking.
• sample_rate (optional) — 0.0–1.0 float. Default 1.0.
• before_send (optional) — callable that takes an event dict and returns it, a modified copy, or None to drop.
• ignore_errors (optional) — list of exception classes or regex patterns to skip.

The highest-volume Python exceptions across Flask, FastAPI, and Django apps, with walk-through fix guides:

• AttributeError: 'NoneType' object has no attribute
• Django database connection errors
• InconsistentMigrationHistory
• Django N+1 query
• CSRF verification failed
• FastAPI validation TypeError
• Flask ImportError (circular imports)
• Flask KeyError on request data

Events not arriving? Check that bugstack.init() runs on import, not inside a request handler. In Gunicorn/uWSGI setups, each worker initializes once — add the call to your app factory.

Seeing the error logged twice? You probably have both bugstack and a framework-level error handler (Flask's default app.logger or Django's logging config) writing to the same sink. bugstack doesn't replace your logger — it reports in parallel.

Async endpoint exceptions missing? For FastAPI with custom async middleware, ensure your middleware calls await call_next(request) inside a try/except that re-raises. Swallowing exceptions in middleware hides them from every error reporter.

See the full Python installation guide for Django settings wiring, async context propagation, and Celery deep integration.

bugstack ships the exception class, message, full traceback, request path, HTTP method, and response status to the API. It does not ship request bodies, form data, cookies, or auth headers unless you explicitly include them via before_send. The GitHub App reads only the files named in the traceback (plus their immediate imports) — not your entire codebase. All data is encrypted in transit with TLS 1.3 and at rest with AES-256, and project data can be deleted at any time from the dashboard. Full details in the data handling doc.

The SDK follows semver. Python 3.9+ is supported. Flask 2.x and 3.x are both supported. FastAPI 0.95+ (including all 1.x pre-releases). Django 4.2 LTS and 5.x. Celery 5.x. The package is pure Python — no C extensions, no compile step. pip install bugstack is the whole install, and it has zero runtime dependencies beyond httpx for HTTP transport.

View the full source code, report issues, and contribute on GitHub.

← Back to Documentation