Improve error messages and metrics for unhandled errors (#1933)

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.

Author: edmorley

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## [Unreleased]
 
+- Improved error messages and metrics for unhandled buildpack errors. ([#1933](https://github.com/heroku/heroku-buildpack-python/pull/1933))
 
 ## [v313] - 2025-10-09
 

bin/compile

@@ -2,7 +2,9 @@
 # Usage: bin/compile <build-dir> <cache-dir> <env-dir>
 # See: https://devcenter.heroku.com/articles/buildpack-api
 
-set -euo pipefail
+# We use `errtrace` and `inherit_errexit` to ensure the ERR trap and exit on error behaviour
+# propagates to buildpack functions run in subshells, such when using command substitutions.
+set -eu -o pipefail -o errtrace
 shopt -s inherit_errexit
 
 # Note: This can't be enabled via app config vars, since at this point they haven't been loaded from ENV_DIR.
@@ -39,6 +41,8 @@ compile_start_time=$(build_data::current_unix_realtime)
 # a build report that will be consumed by the build system for observability.
 build_data::setup
 
+trap 'utils::err_trap' ERR
+
 checks::ensure_supported_stack "${STACK:?"Required env var STACK isn't set"}"
 checks::duplicate_python_buildpack "${BUILD_DIR}"
 

lib/build_data.sh

@@ -109,6 +109,19 @@ function build_data::_set() {
 	echo "${new_data_file_contents}" >"${BUILD_DATA_FILE}"
 }
 
+# Check whether an entry exists in the build data store for the current build.
+# Returns zero if the key was found and non-zero otherwise.
+#
+# Usage:
+# ```
+# build_data::has "failure_reason"
+# ```
+function build_data::has() {
+	local key="${1}"
+
+	jq --exit-status "has(\"${key}\")" "${BUILD_DATA_FILE}" >/dev/null
+}
+
 # Retrieve the value of an entry in the build data store from the previous successful build.
 # Returns the empty string if the key wasn't found in the store.
 #

lib/utils.sh

@@ -66,3 +66,39 @@ function utils::abort_internal_error() {
 	build_data::set_string "failure_detail" "${message}"
 	exit 1
 }
+
+function utils::err_trap() {
+	# We use `errtrace` which means the ERR trap can fire multiple times, such as when an error
+	# occurs in a buildpack function called from within a command substitution.
+	# shellcheck disable=SC2310 # This function is invoked in an 'if' condition so set -e will be disabled.
+	if build_data::has "failure_reason"; then
+		return
+	fi
+
+	local failing_command="${BASH_COMMAND}"
+	local stack_trace
+	stack_trace=$(
+		local frame=0
+		while read -r line_number function_name source_file < <(caller "${frame}" || true); do
+			echo "${function_name} @ ${source_file}:${line_number}"
+			((++frame))
+		done
+	)
+
+	output::error <<-EOF
+		Internal Error: An unhandled buildpack error occurred.
+
+		An unhandled error occurred while executing the command:
+		${failing_command}
+
+		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:
+		${stack_trace}
+	EOF
+	build_data::set_string "failure_reason" "internal-error::unhandled"
+	build_data::set_string "failure_detail" "${failing_command}"
+}