Install the Bugstack Python SDK

The SDK reports uncaught server errors to Bugstack, which reproduces each one as a failing test in an isolated sandbox and sends a proven fix as a pull request. Setup for FastAPI, Flask, Django and plain Python, with the full config reference.

Compatibility

Python 3.9+

Bugstack proves each fix by running your own tests with pytest in its verification sandbox: the reproduction test fails before the change and passes after it, with the rest of your suite green. How the sandbox works.

Install

pip install bugstack

Initialize

Call bugstack.init() once at startup with your API key and the Bugstack endpoint. Pass endpoint explicitly: the published SDK does not default to it yet.

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"),
)

Report an error you handle yourself with bugstack.capture_exception(e).

FastAPI

Initialize, then add the middleware. It reports the exception and re-raises it, so FastAPI's own error handling still runs.

# 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)

Django

Add the middleware and initialize at the end of settings.py:

# 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
]

Flask

# 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

Plain Python

For workers, scripts or any other Python process. Reports are sent from a background thread, so an exception that ends the process can exit before it is sent: report errors where you handle them.

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})

Configuration Reference

Every option is a keyword argument to bugstack.init().

Option Type Default Description
api_key str — Required. Your project API key (starts bsk_).
endpoint str a placeholder address Where reports go. Set it to https://dashboard.bugstack.ai/api/ingest/sdk.
project_id str "" Explicit project identifier.
environment str "production" Environment name sent with each report.
enabled bool True Master switch for error capture.
debug bool False Log SDK activity.
dry_run bool False Log errors instead of sending them.
deduplication_window float 300.0 Seconds during which the same error is sent only once. Bugstack also folds repeats within 24 hours.
timeout float 5.0 HTTP timeout in seconds.
max_retries int 3 Attempts per report, with backoff (1s, 2s).
ignored_errors list [] Exception types, or substrings of messages, not to report.
before_send Callable[[ErrorEvent], ErrorEvent | None] None Change an event before it is sent, or return None to drop it. This is how to remove anything you do not want sent.
auto_fix bool False Sent with each report. What Bugstack does with a fix is set by the repository's autonomy level in Bugstack, not by this flag.

Next Steps

Get started

Sign up with GitHub and start the 14-day trial, or book a demo and we set it up with you. Once the SDK is in, an uncaught server error starts a fix: specialist agents work out the cause and write a small change, it arrives as a pull request that runs through your CI, and what happens next depends on the autonomy level you set. Connecting the repository also starts repository scanning.

Get started Book a demo