diff --git a/examples/bitbucket_pipelines/README.md b/examples/bitbucket_pipelines/README.md
index e5741e07..a0cbe97f 100644
--- a/examples/bitbucket_pipelines/README.md
+++ b/examples/bitbucket_pipelines/README.md
@@ -239,9 +239,10 @@ access the current repository and comment on its pull requests.
 
 ### OCR review produced no output
 
-Verify `OCR_LLM_URL`, `OCR_LLM_AUTH_TOKEN`, and `OCR_LLM_MODEL`. Also confirm
-that the destination branch was fetched and that the PR changes contain file
-types supported by OCR.
+The pipeline prints OCR stderr before failing. Use those diagnostics to verify
+`OCR_LLM_URL`, `OCR_LLM_AUTH_TOKEN`, and `OCR_LLM_MODEL`. Also confirm that the
+destination branch was fetched and that the PR changes contain file types
+supported by OCR.
 
 ### Cannot find a merge base
 
diff --git a/examples/bitbucket_pipelines/bitbucket-pipelines.yml b/examples/bitbucket_pipelines/bitbucket-pipelines.yml
index 841ed90f..cf341a17 100644
--- a/examples/bitbucket_pipelines/bitbucket-pipelines.yml
+++ b/examples/bitbucket_pipelines/bitbucket-pipelines.yml
@@ -58,12 +58,23 @@ definitions:
               "+refs/heads/${BITBUCKET_PR_DESTINATION_BRANCH}:refs/remotes/origin/${BITBUCKET_PR_DESTINATION_BRANCH}"
 
           - |
+            OCR_EXIT_CODE=0
             ocr review \
               --from "origin/${BITBUCKET_PR_DESTINATION_BRANCH}" \
               --to "${BITBUCKET_COMMIT}" \
               --format json \
               --audience agent \
-              > /tmp/ocr-result.json || true
+              > /tmp/ocr-result.json 2> /tmp/ocr-stderr.log || OCR_EXIT_CODE=$?
+
+            if [ -s /tmp/ocr-stderr.log ]; then
+              echo "=== OCR stderr ==="
+              cat /tmp/ocr-stderr.log
+            fi
+
+            if [ "$OCR_EXIT_CODE" -ne 0 ]; then
+              echo "OCR review failed with exit code ${OCR_EXIT_CODE}."
+              exit "$OCR_EXIT_CODE"
+            fi
 
             if [ ! -s /tmp/ocr-result.json ]; then
               echo "OCR review produced no output."