Debugging Applications

Depending on the WSGI gateway/server, exceptions are handleddifferently. Most of the time, exceptions go to stderr or the error log,and a generic “500 Internal Server Error” message is displayed.

Since this is not the best debugging environment, Werkzeug provides aWSGI middleware that renders nice tracebacks, optionally with aninteractive debug console to execute code in any frame.

Danger

The debugger allows the execution of arbitrary code which makes it amajor security risk. The debugger must never be used on productionmachines. We cannot stress this enough. Do not enable the debuggerin production.

Note

The interactive debugger does not work in forking environments, suchas a server that starts multiple processes. Most such environmentsare production servers, where the debugger should not be enabledanyway.

Enabling the Debugger

Enable the debugger by wrapping the application with theDebuggedApplication middleware. Alternatively, you can passuse_debugger=True to run_simple() and it will do that for you.

  • class werkzeug.debug.DebuggedApplication(app, evalex=False, request_key='werkzeug.request', console_path='/console', console_init_func=None, show_hidden_frames=False, lodgeit_url=None, pin_security=True, pin_logging=True)
  • Enables debugging support for a given application:
  1. from werkzeug.debug import DebuggedApplication
  2. from myapp import app
  3. app = DebuggedApplication(app, evalex=True)

The evalex keyword argument allows evaluating expressions in atraceback’s frame context.

New in version 0.9: The lodgeit_url parameter was deprecated.

Parameters:

  • app – the WSGI application to run debugged.
  • evalex – enable exception evaluation feature (interactivedebugging). This requires a non-forking server.
  • request_key – The key that points to the request object in thsenvironment. This parameter is ignored in currentversions.
  • console_path – the URL for a general purpose console.
  • console_init_func – the function that is executed before startingthe general purpose console. The return valueis used as initial namespace.
  • show_hidden_frames – by default hidden traceback frames are skipped.You can show them by setting this parameterto True.
  • pin_security – can be used to disable the pin based security system.
  • pin_logging – enables the logging of the pin system.

Using the Debugger

Once enabled and an error happens during a request you will see adetailed traceback instead of a generic “internal server error”. Thetraceback is still output to the terminal as well.

The error message is displayed at the top. Clicking it jumps to thebottom of the traceback. Frames that represent user code, as opposed tobuilt-ins or installed packages, are highlighted blue. Clicking aframe will show more lines for context, clicking again will hide them.

If you have the evalex feature enabled you can get a console forevery frame in the traceback by hovering over a frame and clicking theconsole icon that appears at the right. Once clicked a console openswhere you can execute Python code in:a screenshot of the interactive debuggerInside the interactive consoles you can execute any kind of Python code.Unlike regular Python consoles the output of the object reprs is coloredand stripped to a reasonable size by default. If the output is longerthan what the console decides to display a small plus sign is added tothe repr and a click will expand the repr.

To display all variables that are defined in the current frame you canuse the dump() function. You can call it without arguments to get adetailed list of all variables and their values, or with an object asargument to get a detailed list of all the attributes it has.

Debugger PIN

Starting with Werkzeug 0.11 the debug console is protected by a PIN.This is a security helper to make it less likely for the debugger to beexploited if you forget to disable it when deploying to production. ThePIN based authentication is enabled by default.

The first time a console is opened, a dialog will prompt for a PIN thatis printed to the command line. The PIN is generated in a stable waythat is specific to the project. An explicit PIN can be provided throughthe environment variable WERKZEUG_DEBUG_PIN. This can be set to anumber and will become the PIN. This variable can also be set to thevalue off to disable the PIN check entirely.

If an incorrect PIN is entered too many times the server needs to berestarted.

This feature is not meant to entirely secure the debugger. It isintended to make it harder for an attacker to exploit the debugger.Never enable the debugger in production.

Pasting Errors

If you click on the “Traceback (most recent call last)” header, theview switches to a tradition text-based traceback. The text can becopied, or automatically pasted to gist.github.com with one click.