diff --git a/codemagic.yaml b/codemagic.yaml
index 6ffd1b0..d44b10f 100644
--- a/codemagic.yaml
+++ b/codemagic.yaml
@@ -101,9 +101,15 @@ workflows:
           # then archive. use-profiles scans for **/*.xcodeproj under the repo root and sets manual
           # signing (team + profile specifier) on the matching App target.
           xcode-project use-profiles
-          xcode-project build-ipa \
-            --workspace "$XCODE_WORKSPACE" \
-            --scheme "$XCODE_SCHEME"
+          # `xcode-project build-ipa` prints a PRETTIFIED summary and swallows the raw xcodebuild "error:"
+          # lines — a failed archive shows only "Failed to archive" with no reason. On failure, surface the
+          # actual errors from the raw log so we don't have to dig through the artifact.
+          if ! xcode-project build-ipa --workspace "$XCODE_WORKSPACE" --scheme "$XCODE_SCHEME"; then
+            echo "======================= xcodebuild errors ======================="
+            grep -h -E "error:|errSec|Provisioning profile|entitlement|Code ?Sign|does not (support|contain)|requires a provisioning|No profile|No signing|doesn't (include|match)|Command .* failed" /tmp/xcodebuild_logs/*.log 2>/dev/null | grep -vi "warning:" | tail -60 || echo "(no matching lines — open the xcodebuild_logs artifact)"
+            echo "================================================================="
+            exit 1
+          fi
     artifacts:
       - build/ios/ipa/*.ipa
       - /tmp/xcodebuild_logs/*.log