Flask-Exceptional adds Exceptional support to Flask. Exceptional tracks errors in your application, reports them real-time, and gathers the info you need to fix them fast. Visit http://www.exceptional.io to give it a try.


The remaining documentation assumes you have access to an Exceptional account. Installing the extension is simple with pip:

$ pip install Flask-Exceptional

or alternatively with easy_install:

$ easy_install Flask-Exceptional


After installing Flask-Exceptional, all you have to do is create a Flask application, configure the Exceptional API key, and create the Exceptional object. It’s this easy:

from flask import Flask
from flask.ext.exceptional import Exceptional

app = Flask(__name__)
app.config["EXCEPTIONAL_API_KEY"] = "exceptional_forty_character_unique_key"
exceptional = Exceptional(app)

Your application is configured for cloud-based error monitoring! You can verify your configuration is working by calling the Exceptional.test() method:


Check out the following section for more detail on the available Flask-Exceptional configuration settings.


The following configuration settings exist for Flask-Exceptional:


The Exceptional API key for your application. Login to Exceptional, select your app, and click the APP SETTINGS link. The displayed API key is the value to use here.

Attempting to create the extension without supplying an API key will result in a logged warning, but the app will continue to run as normal.

EXCEPTIONAL_DEBUG_URL If your app is running in debug mode, errors are not tracked with Exceptional. Configure this value to capture error data in debug mode. For example, you may use a RequestBin URL to debug your application. JSON error data is POSTed uncompressed to this URL, whereas Exceptional requires the data to be compressed.

A list of codes for HTTP errors that will be tracked with Exceptional.

Defaults to standard HTTP 4xx codes.


A list of values to filter from the parameter data sent to Exceptional. Parameter data includes everything in request.form and request.files.

For example, to filter passwords you might use:

['password', 'password_confirm']


A list of values to filter from the environment data sent to Exceptional. The environment data includes the Flask application config plus the current OS environment. OS environment values are prefixed by 'os.'.

For example, to filter the SQL Alchemy database URI and all OS environment values, use:


Defaults to ['SECRET_KEY']

EXCEPTIONAL_SESSION_FILTER A list of values to filter from the session data sent to Exceptional.
EXCEPTIONAL_HEADER_FILTER A list of values to filter from the HTTP header data sent to Exceptional.
EXCEPTIONAL_COOKIE_FILTER A list of names to filter from the HTTP Cookie header data sent to Exceptional.


All configuration filter lists accept both strings and regular expression patterns.


class flask.ext.exceptional.Exceptional(app=None)

Extension for tracking application errors with Exceptional. Errors are not tracked if DEBUG is True. The application will log a warning if no EXCEPTIONAL_API_KEY has been configured.

Parameters:app – Default None. The Flask application to track errors for. If the app is not provided on creation, then it can be provided later via init_app().
static context(data=None, **kwargs)

Add extra context data to the current tracked exception. The context data is only valid for the current request. Multiple calls to this method will update any existing context with new data.

  • data – Default None. A dictionary of context data.
  • kwargs – A series of keyword arguments to use as context data.

Initialize this Exceptional extension.

Parameters:app – The Flask application to track errors for.
static publish(config, traceback)

Publish the given traceback directly to Exceptional. This method is useful for tracking errors that occur outside the context of a Flask request. For example, this may be called from an asynchronous queue.

  • config – A Flask application configuration object. Accepts either flask.Config or the object types allowed by flask.Config.from_object().
  • traceback – A werkzeug.debug.tbtools.Traceback instance to publish.
static test(config)

Test the given Flask configuration. If configured correctly, an error will be tracked by Exceptional for your app. Unlike the initialized extension, this test will post data to Exceptional, regardless of the configured DEBUG setting.

Parameters:config – The Flask application configuration object to test. Accepts either flask.Config or the object types allowed by flask.Config.from_object().


Version 0.5.4

  • Updated JSON implementation import to work with Flask 0.10.

Version 0.5.3

Version 0.5.2

  • Unwind broken _app_ctx_stack usage.

Version 0.5.1

  • Handle malformed HTTP response status-line from Exceptional.

Version 0.5

  • Updated with Flask 0.8 extension structure recommendations and 0.9 _app_ctx_stack.
  • Added {'application_environment': 'loaded_libraries': {...}} API data.

Version 0.4.9

  • Added the Exceptional.context() method to support Exceptional’s extra context data API.
  • Updated to reference the new exceptional.io domain.

Version 0.4.8

  • Updated to publish UTF-8 encoded data to Exceptional.
  • Added support for request.json data.

Version 0.4.7

  • Added the Exceptional.publish() method to support Exceptional tracking outside the context of a request.

Version 0.4.6

  • Corrected occurred_at timestamp to be formatted as Zulu.
  • Fixed JSON serialization issue by coercing all environment variables to strings.

Version 0.4.5

  • Updated to log a warning on repeated extension initialization attempts.

Version 0.4.4

  • Fixed to workaround Python 2.5 issue where urlopen() raises a HTTPError even though the HTTP response code indicates success.

Version 0.4.3

  • Changed so that app.extensions['exceptional'] targets the Exceptional extension instance.

Version 0.4.2

  • Updated to support Python 2.5.

Version 0.4.1

  • Updated to support Flask 0.7 blueprints.

Version 0.4

  • Updated to support Python 2.6.
  • Added EXCEPTIONAL_DEBUG_URL testing environment variable override.

Version 0.3

  • Updated to handle unreachable Exceptional service API.

Version 0.2

Version 0.1

  • Initial public release.
Fork me on GitHub