From 2cb48ffb9b22fbbd85c893e376117d63d700a71a Mon Sep 17 00:00:00 2001
From: Jay Roy <91830182+JoYizPsyKicK@users.noreply.github.com>
Date: Mon, 2 Feb 2026 22:32:34 +0530
Subject: [PATCH] Improve UnknownPackageError message clarity (#5336)

* Improve UnknownPackageError message clarity

* Add IncompatiblePackageError for architecture-specific tool packages
---
 platformio/package/exception.py         | 9 ++++++---
 platformio/package/manager/_registry.py | 8 ++++++--
 2 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/platformio/package/exception.py b/platformio/package/exception.py
index ba896fae..7f8ff994 100644
--- a/platformio/package/exception.py
+++ b/platformio/package/exception.py
@@ -12,7 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from platformio import util
 from platformio.exception import UserSideException
 
 
@@ -52,9 +51,13 @@ class MissingPackageManifestError(ManifestException):
 
 
 class UnknownPackageError(PackageException):
+    MESSAGE = "Could not find the package with '{0}' requirements"
+
+
+class IncompatiblePackageError(UnknownPackageError):
     MESSAGE = (
-        "Could not find the package with '{0}' requirements for your system '%s'"
-        % util.get_systype()
+        "Could not find a version of the package with '{0}' requirements "
+        "compatible with the '{1}' system"
     )
 
 
diff --git a/platformio/package/manager/_registry.py b/platformio/package/manager/_registry.py
index 4c339be8..be7e062f 100644
--- a/platformio/package/manager/_registry.py
+++ b/platformio/package/manager/_registry.py
@@ -16,8 +16,8 @@ import time
 
 import click
 
-from platformio.package.exception import UnknownPackageError
-from platformio.package.meta import PackageSpec
+from platformio.package.exception import IncompatiblePackageError, UnknownPackageError
+from platformio.package.meta import PackageSpec, PackageType
 from platformio.package.version import cast_version_to_semver
 from platformio.registry.client import RegistryClient
 from platformio.registry.mirror import RegistryFileMirrorIterator
@@ -44,6 +44,10 @@ class PackageManagerRegistryMixin:
 
         pkgfile = self.pick_compatible_pkg_file(version["files"]) if version else None
         if not pkgfile:
+            if self.pkg_type == PackageType.TOOL:
+                from platformio import util
+
+                raise IncompatiblePackageError(spec.humanize(), util.get_systype())
             raise UnknownPackageError(spec.humanize())
 
         for url, checksum in RegistryFileMirrorIterator(pkgfile["download_url"]):