Skip to content

Improve error messages and metrics for unhandled errors#1933

Merged
edmorley merged 1 commit intomainfrom
err-trap
Oct 14, 2025
Merged

Improve error messages and metrics for unhandled errors#1933
edmorley merged 1 commit intomainfrom
err-trap

Conversation

@edmorley
Copy link
Copy Markdown
Member

@edmorley edmorley commented Oct 14, 2025

Adds a Bash ERR trap to catch any unhandled buildpack errors, which displays a more helpful error message (that includes the command being run and the stack trace), as well as setting an appropriate failure reason and detail in the build event payload.

For example:

-----> Using Python 3.13 specified in .python-version
-----> Installing Python 3.13.8
mkdir: cannot create directory ‘/tmp/build_1/.heroku’: Not a directory

 !     Internal Error: An unhandled buildpack error occurred.
 !
 !     An unhandled error occurred while executing the command:
 !     mkdir -p "${install_dir}"
 !
 !     If this issue persists, please open a support ticket or file
 !     an issue on the buildpack's GitHub repository:
 !     https://help.heroku.com/
 !     https://github.com/heroku/heroku-buildpack-python/issues
 !
 !     Stack trace:
 !     python::install @ /tmp/buildpack/lib/python.sh:25
 !     main @ ./bin/compile:170

~ Report:
{
  ...
  "failure_detail": "mkdir -p \"${install_dir}\"",
  "failure_reason": "internal-error::unhandled",
  ...
}

See:

GUS-W-19792272.
GUS-W-19792285.

Adds a Bash ERR trap to catch any unhandled buildpack errors, which
displays a more helpful error message (that includes the command being
run and the stack trace), as well as setting an appropriate failure
reason and detail in the build event payload.

For example:

```
-----> Using Python 3.13 specified in .python-version
-----> Installing Python 3.13.8
mkdir: cannot create directory ‘/tmp/build_1/.heroku’: Not a directory

 !     Internal Error: An unhandled buildpack error occurred.
 !
 !     An unhandled error occurred while executing the command:
 !     mkdir -p "${install_dir}"
 !
 !     If this issue persists, please open a support ticket or file
 !     an issue on the buildpack's GitHub repository:
 !     https://help.heroku.com/
 !     https://github.com/heroku/heroku-buildpack-python/issues
 !
 !     Stack trace:
 !     python::install @ /tmp/buildpack/lib/python.sh:25
 !     main @ ./bin/compile:170

~ Report:
{
  ...
  "failure_detail": "mkdir -p \"${install_dir}\"",
  "failure_reason": "internal-error::unhandled",
  ...
}
```

See:
- https://www.gnu.org/software/bash/manual/html_node/Bourne-Shell-Builtins.html#index-trap
- https://www.gnu.org/software/bash/manual/html_node/Bash-Builtins.html#index-caller
- https://www.gnu.org/software/bash/manual/html_node/Bash-Variables.html
- https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html

GUS-W-19792272.
GUS-W-19792285.
@edmorley edmorley self-assigned this Oct 14, 2025
@edmorley edmorley marked this pull request as ready for review October 14, 2025 13:59
@edmorley edmorley requested a review from a team as a code owner October 14, 2025 13:59
Copy link
Copy Markdown
Contributor

@dzuelke dzuelke left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cool, I like this approach, especially since we discussed this several times and both went back and forth on it and you finally picked an approach ;)

I think capturing the failed command as failure_reason and keeping the trace in the printed message is a good compromise, probably easier to see patterns this way in the data (as opposed to trying to group by a "normalized" trace where line numbers may vary over time).

@edmorley edmorley merged commit 258dfa0 into main Oct 14, 2025
6 checks passed
@edmorley edmorley deleted the err-trap branch October 14, 2025 21:46
@heroku-linguist heroku-linguist Bot mentioned this pull request Oct 15, 2025
edmorley added a commit that referenced this pull request Oct 15, 2025
Since:
- The underlying cause of the errors (a bug in older `ensurepip`) was
  fixed in #1761 and friends.
- As of #1933 the generic error trap now handles all internal errors,
  meaning we don't custom handling for them any more.

GUS-W-19898848.
edmorley added a commit that referenced this pull request Oct 15, 2025
Since:
- The underlying cause of the errors (a bug in older `ensurepip`) was
  fixed in #1761 and friends.
- As of #1933 the generic error trap now handles all internal errors,
  meaning we don't custom handling for them any more.

GUS-W-19898848.
edmorley added a commit that referenced this pull request Oct 15, 2025
Since:
- The underlying cause of the errors (a bug in older `ensurepip`) was
  fixed in #1761 and friends.
- As of #1933 the generic error trap now handles all internal errors,
  meaning we don't custom handling for them any more.

GUS-W-19898848.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants