diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml
index b1d7079..aa5b249 100644
--- a/.gitea/workflows/ci.yml
+++ b/.gitea/workflows/ci.yml
@@ -391,12 +391,26 @@ jobs:
       - name: Run SonarScanner
         run: |
           echo "Starting SonarQube analysis..."
-          sonar-scanner \
-            -Dsonar.projectKey=ansible-infra \
+          if ! sonar-scanner \
+            -Dsonar.projectKey=ansible \
             -Dsonar.sources=. \
             -Dsonar.host.url=${SONAR_HOST_URL} \
             -Dsonar.login=${SONAR_TOKEN} \
-            -X
+            -X; then
+            echo ""
+            echo "❌ SonarScanner analysis failed!"
+            echo ""
+            echo "Common issues:"
+            echo "  1. Project 'ansible' doesn't exist in SonarQube"
+            echo "     → Create it manually in SonarQube UI"
+            echo "  2. Token doesn't have permission to analyze/create project"
+            echo "     → Ensure token has 'Execute Analysis' permission"
+            echo "  3. Token doesn't have 'Create Projects' permission (if project doesn't exist)"
+            echo "     → Grant this permission in SonarQube user settings"
+            echo ""
+            echo "Check SonarQube logs for more details."
+            exit 1
+          fi
         continue-on-error: true
 
   workflow-summary: