diff --git a/.gitea/workflows/docker-publish.yml b/.gitea/workflows/docker-publish.yml
index f37dc1f..3469938 100644
--- a/.gitea/workflows/docker-publish.yml
+++ b/.gitea/workflows/docker-publish.yml
@@ -398,7 +398,7 @@ jobs:
 
   # ── Phase 6: update Hub description (only on real release runs) ────
   update-description:
-    needs: [build-variant]
+    needs: [build-variant, resolve-versions]
     if: |
       always() &&
       needs.build-variant.result == 'success' &&
@@ -417,6 +417,13 @@ jobs:
           # placeholder lives in DOCKER_HUB.md (committed); CI fills it
           # at publish time using the same resolved version that was
           # baked into the variant image. No drift between page and image.
+          if [ -z "${PI_VERSION}" ]; then
+            echo "::error::PI_VERSION env var is empty. Likely cause: the"
+            echo "::error::update-description job is missing 'resolve-versions'"
+            echo "::error::in its needs: list, so needs.resolve-versions.outputs.pi_version"
+            echo "::error::resolves to an empty string instead of the actual version."
+            exit 1
+          fi
           cp DOCKER_HUB.md /tmp/hub-full.md
           sed -i "s/{{PI_VERSION}}/${PI_VERSION}/g" /tmp/hub-full.md
           if grep -q '{{PI_VERSION}}' /tmp/hub-full.md; then