Opened 3 years ago

Closed 3 years ago

#19923 closed Cleanup/optimization (fixed)

traceback handling in management commands

Reported by: nkryptic Owned by: nobody
Component: Core (Management commands) Version: master
Severity: Normal Keywords:
Cc: nkryptic@… Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no


The default behavior for management commands to suppress tracebacks, unless the --traceback option is provide can lead to confusion. While the single-line CommandError output is superb, both in it's simplicity and accuracy and the output for other errors raised directly in the management commands are generally clear, the output for errors occurring elsewhere leave users wondering what to do.

For example, runserver provides some clear error messages:

$ ./ runserver
CommandError: "" is not a valid port number or address:port pair.


$ ./ runserver 80
Error: You don't have permission to access that port.

Now, see what happens when I make a mistake in my code:

$ ./ shell
ImportError: cannot import name model

So, I left the s of models somewhere in my code, but I have no idea where. Oddly enough, the runserver command will provide a traceback without needing --traceback:

$ ./ runserver
Validating models...
Unhandled exception in thread started by <bound method Command.inner_run of < object at 0x101d7e310>>
Traceback (most recent call last):
File "/home/me/projects/testproject/testapp/", line 5, in <module>

from . import model

ImportError: cannot import name model

Over the past few weeks, the number of times that I've helped someone by simply introducing them to the use of --traceback on #django was a shock.

Here are some options to consider which may improve this situation:

  1. Always display the tracebacks. The concise messages provided from CommandError will still be displayed at the end, although the length of the traceback may diminish the visibility of it. This would lead to the deprecation of the --traceback option.
  1. If --traceback isn't provided when running a command, append something like the following after the pretty error is displayed:

add --traceback to the prior command to display more information about the error

  1. Introduce users to --traceback usage early. Perhaps a subsection in the tutorial discussing that everyone will make mistakes writing code and how you would go about debugging them in with Django?
  1. Update the management commands to wrap all localized errors with CommandError and the format the display of all CommandErrors without any traceback. Any other error raised would always be formatted and displayed with it's traceback. This also would lead to the deprecation of the --traceback option.

I'm in favor of simply always displaying the tracebacks. I'm not sure how feasible #4 would be, but if it is possible and straightforward to do, that would be even better.

Attachments (2)

19923-1.diff (2.8 KB) - added by claudep 3 years ago.
19923-2.diff (3.5 KB) - added by claudep 3 years ago.
Same patch including updated docs

Download all attachments as: .zip

Change History (5)

comment:1 Changed 3 years ago by claudep

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted
  • Type changed from Uncategorized to Cleanup/optimization

I also think that not all errors are equal. When I see for example compilemessages raising "The %s file has a BOM (Byte Order Mark). Django only supports .po files encoded in UTF-8 and without any BOM.", a traceback would seldom be useful IMHO.

I'd lean towards something like:

  • Keep --traceback to force traceback display for all exceptions.
  • Always display tracebacks for exceptions other than CommandError.
  • Check CommandErrors to see if some might benefit from a traceback, and then add an optional parameter to CommandError, so as we can make a distinction and display traceback by default for some CommandErrors.

Changed 3 years ago by claudep

comment:2 Changed 3 years ago by claudep

  • Easy pickings set
  • Has patch set

Attached is a patch implementing the basic idea of always displaying tracebacks for non-CommandError exceptions.

Changed 3 years ago by claudep

Same patch including updated docs

comment:3 Changed 3 years ago by Claude Paroz <claude@…>

  • Resolution set to fixed
  • Status changed from new to closed

In 6a91b638423de954b7d96c38e2372100800139fb:

Fixed #19923 -- Display tracebacks for non-CommandError exceptions

By default, show tracebacks for management command errors when the
exception is not a CommandError.
Thanks Jacob Radford for the report.

Note: See TracTickets for help on using tickets.
Back to Top