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.