Python SDK reference

Initialize, then add the middleware. It reports an unhandled exception in a request and re-raises it.

# In your main app file, after the FastAPI app is created:
import os
import bugstack
from bugstack.integrations.fastapi import FastAPIMiddleware

bugstack.init(
    api_key=os.environ.get("BUGSTACK_API_KEY", ""),
    endpoint=os.environ.get("BUGSTACK_ENDPOINT", "https://dashboard.bugstack.ai/api/ingest/sdk"),
)
app.add_middleware(FastAPIMiddleware)

# In your main app file, after the Flask app is created:
import os
import bugstack
from flask import request
from werkzeug.exceptions import HTTPException

bugstack.init(
    api_key=os.environ.get("BUGSTACK_API_KEY", ""),
    endpoint=os.environ.get("BUGSTACK_ENDPOINT", "https://dashboard.bugstack.ai/api/ingest/sdk"),
)

# Report unhandled errors (or add the capture call to your existing handler):
@app.errorhandler(Exception)
def handle_exception(e):
    if isinstance(e, HTTPException):
        return e  # 404s and other HTTP errors keep their own response
    bugstack.capture_exception(
        e,
        request=bugstack.RequestContext(
            route=request.url_rule.rule if request.url_rule else request.path,
            method=request.method,
        ),
    )
    return {"error": "Internal Server Error"}, 500

Add the middleware and initialize at the end of settings.py. (The middleware can also initialize itself from BUGSTACK_API_KEY and other BUGSTACK_* settings, but not with an endpoint, so call bugstack.init yourself.)

# settings.py
import os
import bugstack

bugstack.init(
    api_key=os.environ.get("BUGSTACK_API_KEY", ""),
    endpoint=os.environ.get("BUGSTACK_ENDPOINT", "https://dashboard.bugstack.ai/api/ingest/sdk"),
)

MIDDLEWARE = [
    "bugstack.integrations.django.BugStackMiddleware",
    # ... your other middleware
]

import os
import bugstack
from bugstack.integrations.generic import install_hooks

bugstack.init(
    api_key=os.environ.get("BUGSTACK_API_KEY", ""),
    endpoint=os.environ.get("BUGSTACK_ENDPOINT", "https://dashboard.bugstack.ai/api/ingest/sdk"),
)
install_hooks()  # uncaught exceptions in the main thread and in threads

# Or report an error you handle yourself:
try:
    process_job(job)
except Exception as e:
    bugstack.capture_exception(e, metadata={"job": job.id})

An unhandled exception in a FastAPI, Flask or Django request, an uncaught exception in the main thread or a thread once install_hooks() has run, and anything you pass to bugstack.capture_exception. Celery, RQ and other job queues are not hooked: report job errors with capture_exception.

Each report carries the exception type, message and stack trace, the file and function it came from, the route and method of the request, the Python version, framework and SDK version, and any metadata you pass. Query parameters, headers and request bodies are not sent. Reports go out from a background thread, with up to three attempts; an exception that ends the process can exit before its report is sent.

• bugstack.capture_exception(exc=None, *, request=None, metadata=None): report an exception (the one being handled, if you pass none). Returns True if it was accepted.
• bugstack.get_client(): the current client, or None before init.
• bugstack.integrations.generic.install_hooks() and uninstall_hooks(): report uncaught exceptions through sys.excepthook and threading.excepthook.

Every option, with its type and default, is in the installation guide. The ones you are most likely to set: api_key, endpoint, environment, enabled, ignored_errors and before_send.

Specialist agents work out the cause and write the change. It arrives as a pull request your own CI runs on. What happens next depends on the autonomy level you set for the repository: new repositories start on Review, where you merge. Before Autopilot merges a crash fix, bugstack replays the failing request: it must fail before the fix and pass after; without that proof the pull request waits for you. Connecting the repository also starts repository scanning.

Error patterns that come up often in production Python applications. Each link opens a step-by-step fix guide:

• 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

No events in bugstack? Check that the API key is set when the process starts, and that endpoint is set to https://dashboard.bugstack.ai/api/ingest/sdk: the published SDK does not default to it yet. Turn on debug to see each send.

Events but no fix pull request? The bugstack GitHub App must be installed on the repository, and the files in the stack trace must be in that repository.

Too many duplicates? Each SDK sends the same error at most once every five minutes, and bugstack folds repeats within 24 hours into the same piece of work, so you get one pull request per problem.

Errors from a short script never arrive? Reports are sent from a background thread, so a process that exits right after an error can end before the send. Report errors where you handle them, in a process that keeps running.

The SDK sends the exception, its stack trace, the file and function, the route and method, and runtime details. It does not send query parameters, headers or request bodies, and it does not redact the exception message or stack trace: use before_send to change or drop an event before it is sent. See privacy and data handling.

The bugstack package follows semver. It needs Python 3.9 or later and depends only on httpx. Its framework extras ask for FastAPI 0.95+, Flask 2+ and Django 3.2+.

Sign up with GitHub and start Pro, or book a call and we set it up with you. Get started.

← Back to Documentation