Debugging

Using the Python debugger

You can configure Litestar to drop into the Python Debugger when an exception occurs. This can be configured in different ways:

Configuring Litestar with the pdb_on_exception option

app = Litestar(pdb_on_exception=True)

Running your app with the CLI and using the --pdb flag

litestar run --pdb

Using the LITESTAR_PDB environment variable

LITESTAR_PDB=1

Debugging with an IDE

You can easily attach your IDEs debugger to your application, whether you’re running it via the CLI or a webserver like uvicorn.

Intellij / PyCharm

Using the CLI

1. Create a new debug configuration via Run > Edit Configurations

2. Select Module name option and set it to litestar

3. Add the run parameter and optionally additional parameters you want to pass to the CLI

   

4. Run your application in the debugger via Run > Debug Litestar

   

Important

Breakpoints inside route handlers might not work correctly when used in conjunction with the --reload and --web-concurrency parameters. If you want to use the CLI while making use of these options, you can attach the debugger manually to the running uvicorn process via Run > Attach to process.

Using uvicorn

1. Create a new debug configuration via Run > Edit Configurations

2. Select Module name option and set it to uvicorn

3. Add the app:app parameter (or the equivalent path to your application object)

   

4. Run your application in the debugger via Run > Debug Litestar

   

VS Code

Using the CLI

1. Add a new debugging configuration via Run > Add configuration

   

2. From the Select a debug configuration dialog, select Module

   

3. Enter litestar as the module name

   

4. In the opened JSON file, alter the configuration as follows:

   {
       "name": "Python: Litestar app",
       "type": "python",
       "request": "launch",
       "module": "litestar",
       "justMyCode": true,
       "args": ["run"]
   }
   

5. Run your application via the debugger via Run > Start debugging

   

Using uvicorn

1. Add a new debugging configuration via Run > Add configuration

   

2. From the Select a debug configuration dialog, select Module

   

3. Enter uvicorn as the module name

   

4. In the opened JSON file, alter the configuration as follows:

   {
       "name": "Python: Litestar app",
       "type": "python",
       "request": "launch",
       "module": "uvicorn",
       "justMyCode": true,
       "args": ["app:app"]
   }
   

5. Run your application via the debugger via Run > Start debugging

   

Customizing the debugger

You can configure Litestar with the debug_module option to enable interactive debugging. Currently, it supports the following debugging tools: ipdb, PuDB and pdbr. Also supports pdb++. The default value is pdb.

import ipdb


app = Litestar(pdb_on_exception=True, debugger_module=ipdb)