[App Service] Fix #29290: Improve error messages for az webapp deploy --src-url failures

When `az webapp deploy --src-url` receives non-2xx HTTP responses,
`send_raw_request` raises `HTTPError` before the deploy-specific error
handling code is reached. This results in bare error messages like
"Bad Request" with no actionable guidance.

This change adds a `_send_deploy_request` wrapper that catches HTTP errors
on the --src-url ARM deploy path and provides clear, actionable messages:

- 400 Bad Request: troubleshooting guidance for URL accessibility, SAS
  tokens, and artifact type mismatches
- 404 Not Found: guidance to verify resource group, app name, and slot
- 409 Conflict: message about in-progress deployments

The wrapper uses the server-provided reason phrase and includes any
response body details when available. Unhandled status codes re-raise
the original HTTPError unchanged.

Fixes #29290

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: seligj95

.gitignore

@@ -123,3 +123,11 @@ cmd_coverage/*
 
 # Ignore test results
 test_results.xml
+
+# Squad agent framework (local only — never commit)
+.squad/
+.squad-workstream
+.github/agents/squad.agent.md
+.github/workflows/squad-*.yml
+.github/workflows/sync-squad-labels.yml
+.copilot/

src/azure-cli/azure/cli/command_modules/appservice/custom.py

@@ -9781,6 +9781,43 @@ def _warmup_kudu_and_get_cookie_internal(params):
     return None
 
 
+def _send_deploy_request(cli_ctx, deploy_url, body):
+    """Wrapper around send_raw_request for --src-url deployments that provides
+    actionable error messages instead of bare HTTP status codes."""
+    from azure.cli.core.azclierror import HTTPError
+    try:
+        return send_raw_request(cli_ctx, "PUT", deploy_url, body=body)
+    except HTTPError as ex:
+        resp = ex.response
+        status_code = resp.status_code if resp is not None else None
+        response_text = resp.text if resp is not None else ""
+        reason = getattr(resp, 'reason', None) or "Unknown"
+        error_detail = f" Details: {response_text}" if response_text else ""
+        if status_code == 400:
+            raise CLIError(
+                f"Deployment from URL failed with status 400 ({reason}).{error_detail}\n"
+                "Possible causes:\n"
+                "  - The source URL is not publicly accessible or the SAS token has expired\n"
+                "  - The URL does not point to a valid deployment artifact\n"
+                "  - The artifact type does not match the file content (e.g., --type zip for a non-zip file)\n"
+                "Please verify the URL is accessible and the artifact type is correct."
+            ) from ex
+        if status_code == 404:
+            raise ResourceNotFoundError(
+                f"Deployment from URL failed with status 404 ({reason}).{error_detail}\n"
+                "The target app or OneDeploy endpoint could not be found. "
+                "Verify that the resource group, app name, and slot (if any) are correct, "
+                "and that the app still exists."
+            ) from ex
+        if status_code == 409:
+            raise ValidationError(
+                f"Deployment from URL failed with status 409 ({reason}).{error_detail}\n"
+                "Another deployment is currently in progress. Please wait for the existing "
+                "deployment to complete before starting a new one."
+            ) from ex
+        raise
+
+
 def _make_onedeploy_request(params):
     import requests
     from azure.cli.core.util import should_disable_connection_verify
@@ -9828,16 +9865,16 @@ def _make_onedeploy_request(params):
                 if cookies is None:
                     logger.info("Failed to fetch affinity cookie for Kudu. "
                                 "Deployment will proceed without pre-warming a Kudu instance.")
-                    response = send_raw_request(params.cmd.cli_ctx, "PUT", deploy_url, body=body)
+                    response = _send_deploy_request(params.cmd.cli_ctx, deploy_url, body)
                 else:
                     deploy_arm_url = _build_onedeploy_url(params, cookies.get("ARRAffinity"))
-                    response = send_raw_request(params.cmd.cli_ctx, "PUT", deploy_arm_url, body=body)
+                    response = _send_deploy_request(params.cmd.cli_ctx, deploy_arm_url, body)
             except Exception as ex:  # pylint: disable=broad-except
                 logger.info("Failed to deploy using instances endpoint. "
                             "Deployment will proceed without pre-warming a Kudu instance. Ex: %s", ex)
-                response = send_raw_request(params.cmd.cli_ctx, "PUT", deploy_url, body=body)
+                response = _send_deploy_request(params.cmd.cli_ctx, deploy_url, body)
         else:
-            response = send_raw_request(params.cmd.cli_ctx, "PUT", deploy_url, body=body)
+            response = _send_deploy_request(params.cmd.cli_ctx, deploy_url, body)
         poll_async_deployment_for_debugging = False
 
     # check the status of deployment

src/azure-cli/azure/cli/command_modules/appservice/tests/latest/test_webapp_commands_thru_mock.py

@@ -12,7 +12,9 @@
 from knack.util import CLIError
 from azure.cli.core.azclierror import (InvalidArgumentValueError,
                                        MutuallyExclusiveArgumentError,
-                                       AzureResponseError)
+                                       AzureResponseError,
+                                       ResourceNotFoundError,
+                                       ValidationError)
 from azure.cli.command_modules.appservice.custom import (set_deployment_user,
                                                          update_git_token, add_hostname,
                                                          update_site_configs,
@@ -33,7 +35,8 @@
                                                          add_github_actions,
                                                          update_app_settings,
                                                          update_application_settings_polling,
-                                                         update_webapp)
+                                                         update_webapp,
+                                                         _send_deploy_request)
 
 # pylint: disable=line-too-long
 from azure.cli.core.profiles import ResourceType
@@ -639,6 +642,118 @@ def test_update_webapp_platform_release_channel_latest(self):
         self.assertEqual(result.additional_properties["properties"]["platformReleaseChannel"], "Latest")
 
 
+class TestSendDeployRequest(unittest.TestCase):
+    """Tests for _send_deploy_request wrapper that provides actionable error messages."""
+
+    @mock.patch('azure.cli.command_modules.appservice.custom.send_raw_request')
+    def test_success_passes_through(self, send_raw_request_mock):
+        """Successful responses (200/202) should pass through unchanged."""
+        cli_ctx = _get_test_cmd().cli_ctx
+        response = mock.MagicMock()
+        response.status_code = 202
+        send_raw_request_mock.return_value = response
+
+        result = _send_deploy_request(cli_ctx, 'https://management.azure.com/deploy', '{"properties":{}}')
+
+        self.assertEqual(result, response)
+        send_raw_request_mock.assert_called_once_with(
+            cli_ctx, "PUT", 'https://management.azure.com/deploy', body='{"properties":{}}'
+        )
+
+    @mock.patch('azure.cli.command_modules.appservice.custom.send_raw_request')
+    def test_400_with_empty_body_gives_actionable_error(self, send_raw_request_mock):
+        """HTTP 400 with empty body should produce a helpful error message instead of bare 'Bad Request'."""
+        from azure.cli.core.azclierror import HTTPError
+        cli_ctx = _get_test_cmd().cli_ctx
+
+        response = mock.MagicMock()
+        response.status_code = 400
+        response.reason = "Bad Request"
+        response.text = ""
+        send_raw_request_mock.side_effect = HTTPError("Bad Request", response)
+
+        with self.assertRaises(CLIError) as ctx:
+            _send_deploy_request(cli_ctx, 'https://management.azure.com/deploy', '{"properties":{}}')
+
+        error_msg = str(ctx.exception)
+        self.assertIn("Deployment from URL failed with status 400 (Bad Request)", error_msg)
+        self.assertIn("source URL is not publicly accessible", error_msg)
+        self.assertIn("SAS token has expired", error_msg)
+        self.assertIn("artifact type does not match", error_msg)
+
+    @mock.patch('azure.cli.command_modules.appservice.custom.send_raw_request')
+    def test_400_with_response_body_includes_details(self, send_raw_request_mock):
+        """HTTP 400 with a response body should include the details in the error."""
+        from azure.cli.core.azclierror import HTTPError
+        cli_ctx = _get_test_cmd().cli_ctx
+
+        response = mock.MagicMock()
+        response.status_code = 400
+        response.reason = "Bad Request"
+        response.text = "Invalid package URI"
+        send_raw_request_mock.side_effect = HTTPError("Bad Request(Invalid package URI)", response)
+
+        with self.assertRaises(CLIError) as ctx:
+            _send_deploy_request(cli_ctx, 'https://management.azure.com/deploy', '{"properties":{}}')
+
+        error_msg = str(ctx.exception)
+        self.assertIn("Deployment from URL failed with status 400", error_msg)
+        self.assertIn("Invalid package URI", error_msg)
+
+    @mock.patch('azure.cli.command_modules.appservice.custom.send_raw_request')
+    def test_404_gives_not_found_error(self, send_raw_request_mock):
+        """HTTP 404 should raise ResourceNotFoundError with guidance."""
+        from azure.cli.core.azclierror import HTTPError
+        cli_ctx = _get_test_cmd().cli_ctx
+
+        response = mock.MagicMock()
+        response.status_code = 404
+        response.reason = "Not Found"
+        response.text = ""
+        send_raw_request_mock.side_effect = HTTPError("Not Found", response)
+
+        with self.assertRaises(ResourceNotFoundError) as ctx:
+            _send_deploy_request(cli_ctx, 'https://management.azure.com/deploy', '{"properties":{}}')
+
+        error_msg = str(ctx.exception)
+        self.assertIn("Deployment from URL failed with status 404", error_msg)
+        self.assertIn("app or OneDeploy endpoint could not be found", error_msg)
+
+    @mock.patch('azure.cli.command_modules.appservice.custom.send_raw_request')
+    def test_409_gives_conflict_error(self, send_raw_request_mock):
+        """HTTP 409 should raise ValidationError about in-progress deployment."""
+        from azure.cli.core.azclierror import HTTPError
+        cli_ctx = _get_test_cmd().cli_ctx
+
+        response = mock.MagicMock()
+        response.status_code = 409
+        response.reason = "Conflict"
+        response.text = ""
+        send_raw_request_mock.side_effect = HTTPError("Conflict", response)
+
+        with self.assertRaises(ValidationError) as ctx:
+            _send_deploy_request(cli_ctx, 'https://management.azure.com/deploy', '{"properties":{}}')
+
+        error_msg = str(ctx.exception)
+        self.assertIn("Deployment from URL failed with status 409", error_msg)
+        self.assertIn("Another deployment is currently in progress", error_msg)
+
+    @mock.patch('azure.cli.command_modules.appservice.custom.send_raw_request')
+    def test_unhandled_error_reraises(self, send_raw_request_mock):
+        """Unhandled HTTP errors (e.g., 500) should re-raise without modification."""
+        from azure.cli.core.azclierror import HTTPError
+        cli_ctx = _get_test_cmd().cli_ctx
+
+        response = mock.MagicMock()
+        response.status_code = 500
+        response.reason = "Internal Server Error"
+        response.text = "Internal Server Error"
+        send_raw_request_mock.side_effect = HTTPError("Internal Server Error", response)
+
+        with self.assertRaises(HTTPError):
+            _send_deploy_request(cli_ctx, 'https://management.azure.com/deploy', '{"properties":{}}')
+
+
 class FakedResponse:  # pylint: disable=too-few-public-methods
     def __init__(self, status_code):
         self.status_code = status_code