improve error messages

Author: Seppli11

src/pysonar_scanner/__main__.py

@@ -74,13 +74,15 @@ def build_api(config: dict[str, any]) -> SonarQubeApi:
     return SonarQubeApi(base_urls, token)
 
 
-def check_version(api):
+def check_version(api: SonarQubeApi):
     if api.is_sonar_qube_cloud():
         return
     version = api.get_analysis_version()
     if not version.does_support_bootstrapping():
         raise SQTooOldException(
-            f"Only SonarQube versions >= {MIN_SUPPORTED_SQ_VERSION} are supported, but got {version}"
+            f"This scanner only supports SonarQube versions >= {MIN_SUPPORTED_SQ_VERSION}. \n"
+            f"The server at {api.base_urls.base_url} is on version {version}\n"
+            "Please either upgrade your SonarQube server or use the Sonar Scanner CLI (see https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/scanners/sonarscanner/)."
         )
 
 

src/pysonar_scanner/api.py

@@ -19,7 +19,7 @@
 #
 import typing
 from dataclasses import dataclass
-from typing import Optional, TypedDict
+from typing import NoReturn, Optional, TypedDict
 
 import requests
 import requests.auth
@@ -32,7 +32,11 @@
     Key,
 )
 from pysonar_scanner.utils import remove_trailing_slash, OsStr, ArchStr
-from pysonar_scanner.exceptions import SonarQubeApiException, InconsistentConfiguration
+from pysonar_scanner.exceptions import (
+    SonarQubeApiException,
+    InconsistentConfiguration,
+    SonarQubeApiUnauthroizedException,
+)
 
 GLOBAL_SONARCLOUD_URL = "https://sonarcloud.io"
 US_SONARCLOUD_URL = "https://sonarqube.us"
@@ -185,6 +189,16 @@ def __init__(self, base_urls: BaseUrls, token: str):
         self.base_urls = base_urls
         self.auth = BearerAuth(token)
 
+    def __raise_exception(self, exception: Exception) -> NoReturn:
+        if (
+            isinstance(exception, requests.RequestException)
+            and exception.response is not None
+            and exception.response.status_code == 401
+        ):
+            raise SonarQubeApiUnauthroizedException.create_default(self.base_urls.base_url) from exception
+        else:
+            raise SonarQubeApiException("Error while fetching the analysis version") from exception
+
     def is_sonar_qube_cloud(self) -> bool:
         return self.base_urls.is_sonar_qube_cloud
 
@@ -197,7 +211,7 @@ def get_analysis_version(self) -> SQVersion:
             res.raise_for_status()
             return SQVersion.from_str(res.text)
         except requests.RequestException as e:
-            raise SonarQubeApiException("Error while fetching the analysis version") from e
+            self.__raise_exception(e)
 
     def get_analysis_engine(self) -> EngineInfo:
         try:
@@ -210,7 +224,7 @@ def get_analysis_engine(self) -> EngineInfo:
                 raise SonarQubeApiException("Invalid response from the server")
             return EngineInfo(filename=json["filename"], sha256=json["sha256"])
         except requests.RequestException as e:
-            raise SonarQubeApiException("Error while fetching the analysis engine information") from e
+            self.__raise_exception(e)
 
     def download_analysis_engine(self, handle: typing.BinaryIO) -> None:
         """
@@ -226,7 +240,7 @@ def download_analysis_engine(self, handle: typing.BinaryIO) -> None:
             )
             self.__download_file(res, handle)
         except requests.RequestException as e:
-            raise SonarQubeApiException("Error while fetching the analysis engine") from e
+            self.__raise_exception(e)
 
     def get_analysis_jres(self, os: OsStr, arch: ArchStr) -> list[JRE]:
         try:
@@ -241,7 +255,7 @@ def get_analysis_jres(self, os: OsStr, arch: ArchStr) -> list[JRE]:
             json_array = res.json()
             return [JRE.from_dict(jre) for jre in json_array]
         except (requests.RequestException, KeyError) as e:
-            raise SonarQubeApiException("Error while fetching the analysis version") from e
+            self.__raise_exception(e)
 
     def download_analysis_jre(self, id: str, handle: typing.BinaryIO) -> None:
         """
@@ -257,7 +271,7 @@ def download_analysis_jre(self, id: str, handle: typing.BinaryIO) -> None:
             )
             self.__download_file(res, handle)
         except requests.RequestException as e:
-            raise SonarQubeApiException("Error while fetching the JRE") from e
+            self.__raise_exception(e)
 
     def __download_file(self, res: requests.Response, handle: typing.BinaryIO) -> None:
         res.raise_for_status()

src/pysonar_scanner/configuration/cli.py

@@ -37,7 +37,7 @@ def load(cls) -> dict[str, any]:
         # Handle unknown args starting with '-D'
         for arg in unknown_args:
             if not arg.startswith("-D"):
-                raise UnexpectedCliArgument(f"Unexpected argument: {arg}")
+                raise UnexpectedCliArgument(f"Unexpected argument: {arg}\nRun with --help for more information.")
             key_value = arg[2:].split("=", 1)
             if len(key_value) == 2:
                 key, value = key_value

src/pysonar_scanner/exceptions.py

@@ -35,13 +35,28 @@ class MissingPropertyException(Exception):
     @staticmethod
     def from_missing_keys(*properties: MissingProperty) -> "MissingPropertyException":
         missing_properties = ", ".join([f"{prop.property} ({prop.cli_arg})" for prop in properties])
-        return MissingPropertyException(f"Missing required properties: {missing_properties}")
+        fix_message = (
+            "You can provide these properties using one of the following methods:\n"
+            "- Command line arguments (e.g., --sonar.projectKey=myproject)\n"
+            "- Environment variables (e.g., SONAR_PROJECTKEY=myproject)\n"
+            "- Properties file (sonar-project.properties)\n"
+            "- Project configuration files (e.g., build.gradle, pom.xml)"
+        )
+        return MissingPropertyException(f"Missing required properties: {missing_properties}\n\n{fix_message}")
 
 
 class SonarQubeApiException(Exception):
     pass
 
 
+class SonarQubeApiUnauthroizedException(SonarQubeApiException):
+    @staticmethod
+    def create_default(server_url: str) -> "SonarQubeApiUnauthroizedException":
+        return SonarQubeApiUnauthroizedException(
+            f'The provided token is invalid for the server at "{server_url}". Please check that both the token and the server URL are correct.'
+        )
+
+
 class SQTooOldException(Exception):
     pass
 
@@ -51,7 +66,9 @@ class InconsistentConfiguration(Exception):
 
 
 class ChecksumException(Exception):
-    pass
+    @staticmethod
+    def create(what: str) -> "ChecksumException":
+        return ChecksumException(f"Checksum mismatch. The downloaded {what} is corrupted.")
 
 
 class UnexpectedCliArgument(Exception):
@@ -74,6 +91,10 @@ def log_error(e: Exception):
     logger = logging.getLogger()
     is_debug_level = logger.getEffectiveLevel() <= logging.DEBUG
 
-    logger.error(str(e), exc_info=is_debug_level)
+    if is_debug_level:
+        logger.error("The following exception occured while running the analysis", exc_info=True)
+    else:
+        logger.error(str(e), exc_info=False)
+        logger.info("For more details, please enable debug logging by passing the --verbose option.")
 
     return EXCEPTION_RETURN_CODE

src/pysonar_scanner/jre.py

@@ -69,9 +69,7 @@ def __attempt_provisioning_jre_with_retry(self) -> tuple[JRE, pathlib.Path]:
         if jre_and_resolved_path is None:
             jre_and_resolved_path = self.__attempt_provisioning_jre()
         if jre_and_resolved_path is None:
-            raise ChecksumException(
-                f"Failed to download and verify JRE for {self.sonar_scanner_os} and {self.sonar_scanner_arch}"
-            )
+            raise ChecksumException.create("JRE")
 
         return jre_and_resolved_path
 
@@ -129,7 +127,9 @@ def __extract_jre(self, file_path: pathlib.Path, unzip_dir: pathlib.Path):
             with tarfile.open(file_path, "r:gz") as tar_ref:
                 tar_ref.extractall(unzip_dir, filter="data")
         else:
-            raise UnsupportedArchiveFormat(f"Unsupported archive format: {file_path.suffix}")
+            raise UnsupportedArchiveFormat(
+                f"Received JRE is packaged as an unsupported archive format: {file_path.suffix}"
+            )
 
 
 @dataclass(frozen=True)

src/pysonar_scanner/scannerengine.py

@@ -119,7 +119,7 @@ def provision(self) -> pathlib.Path:
         if scanner_file is not None:
             return scanner_file.filepath
         else:
-            raise ChecksumException("Failed to download and verify scanner engine")
+            raise ChecksumException.create("scanner engine JAR")
 
     def __download_and_verify(self) -> Optional[CacheFile]:
         engine_info = self.api.get_analysis_engine()

tests/its/test_minimal.py

@@ -46,6 +46,6 @@ def test_minimal_project_unexpected_arg(cli: CliClient):
 
 
 def test_invalid_token(sonarqube_client: SonarQubeClient, cli: CliClient):
-    process = cli.run_analysis(sources_dir="minimal", token="invalid")
+    process = cli.run_analysis(params=["--verbose"], sources_dir="minimal", token="invalid")
     assert process.returncode == 1, str(process.stdout)
-    assert "Error while fetching the analysis version" in process.stdout
+    assert "HTTPError: 401 Client Error" in process.stdout