Bug reportsΒΆ

A command given a report_url ends the run on an error it has no rule for with a bug report. After the traceback of the error comes a block for the user to paste into an issue, and a link to the issue form of the project, with a title filled in:

from click_extra import command, echo, option

@command(report_url="https://github.com/orchard/harvest/issues/new")
@option("--fruit", help="The fruit to share.")
def harvest(fruit):
    """Share the fruits among the baskets."""
    baskets = []
    echo(f"{fruit}: {10 // len(baskets)} per basket")
$ harvest --fruit plum
critical: Unexpected error in harvest:
Traceback (most recent call last):
  File "/home/runner/work/click-extra/click-extra/click_extra/commands.py", line 1098, in invoke
    return super().invoke(ctx)
           ~~~~~~~~~~~~~~^^^^^
  File "/home/runner/work/click-extra/click-extra/.venv/lib/python3.14/site-packages/click/core.py", line 1414, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/click-extra/click-extra/.venv/lib/python3.14/site-packages/click/core.py", line 911, in invoke
    return callback(*args, **kwargs)
  File "/home/runner/work/click-extra/click-extra/docs/bug-report.md:5", line 8, in harvest
ZeroDivisionError: division by zero
critical:
harvest stopped on this error, which is a bug.
Please report it with this form:
https://github.com/orchard/harvest/issues/new?title=ZeroDivisionError+in+harvest
Paste the lines between the two 8< markers into the issue. They hold no file path, and mask the values of paths and arguments. Read the error lines first: an error message can quote your data.
----- 8< ----- bug report ----- 8< -----
harvest, Python 3.14.4, Ubuntu x86-64 (AMD64)
Options: --fruit plum

ZeroDivisionError: division by zero
  ?:8 in harvest
----- 8< ----- end of bug report ----- 8< -----
This report is also saved in this file:
/tmp/tmpmms9tfoj/harvest/reports/bug-report-2026-11-18T13-41-48-htsehm6o.txt

The block gives the version of the CLI, the platform, the options of the run and the traceback of the error. The report is also saved in a file of the cache of the CLI, whose path ends the output: a user who lost the output of the run still finds it there.

The title names the class of the error and the innermost function of the CLI that it went through. Reports of the same bug get the same title, so the issue form of GitHub lists the issue already open for it while the next user types theirs.

What a report holdsΒΆ

Issues are often public, so a report holds no file path. The traceback shows module names and line numbers, which say as much about the code as file paths, and nothing about where it is installed. The options line masks the values of paths, patterns and positional arguments.

The message of the error shows as the code wrote it, and can quote the data of the user: the report asks them to read it before they paste it.

An AI agent that runs the CLI gets one more line. It tells the agent to show the report to its user, and to ask before it files the issue.

Which errors get a reportΒΆ

  • An exception that Click exits with, like a usage error, an abort, an end of input or a broken pipe, is no bug: Click handles it as before.

  • An OSError, like a missing permission or a full disk, is for the user to fix: the run ends with a one-line Error:.

  • Any other error gets a report, and the run exits with code 1.

Set report_url on the root command. On a group, the error of any subcommand then gets one report, which names the subcommand and its options.

A report that does not stop the runΒΆ

log_report() logs a report of the same shape, for a failure that the CLI survives, like an item it set aside:

import logging

from click_extra import command, echo, log_report

@command(report_url="https://github.com/orchard/harvest/issues/new")
def sort_fruits():
    """Sort the fruits, and set aside the ones that fail."""
    log_report(
        logging.WARNING,
        "One fruit was set aside after an unexpected error.",
        "Fruit set aside while sorting",
        ("", "Fruits set aside: 1"),
    )
    echo("Sorted the other fruits.")
$ sort-fruits
warning:
One fruit was set aside after an unexpected error.
Please report it with this form:
https://github.com/orchard/harvest/issues/new?title=Fruit+set+aside+while+sorting
Paste the lines between the two 8< markers into the issue. They hold no file path, and mask the values of paths and arguments. Read the error lines first: an error message can quote your data.
----- 8< ----- bug report ----- 8< -----
sort-fruits, Python 3.14.4, Ubuntu x86-64 (AMD64)
Options: none

Fruits set aside: 1
----- 8< ----- end of bug report ----- 8< -----
This report is also saved in this file:
/tmp/tmp2ojcifkv/sort-fruits/reports/bug-report-2026-11-18T13-41-48-pb4d7hwo.txt
Sorted the other fruits.

compact_frames(), culprit_function() and describe_error() reduce an error to the lines and the title of such a report.