fix: catch remote build errors

requirements-devel.txt

@@ -24,7 +24,7 @@ click==8.1.7
 codespell==2.3.0
 colorama==0.4.6
 coverage==7.6.1
-craft-application==4.2.3
+craft-application==4.2.4
 craft-archives==2.0.0
 craft-cli==2.7.0
 craft-grammar==2.0.1

requirements-docs.txt

@@ -19,7 +19,7 @@ chardet==5.2.0
 charset-normalizer==3.3.2
 click==8.1.7
 colorama==0.4.6
-craft-application==4.2.3
+craft-application==4.2.4
 craft-archives==2.0.0
 craft-cli==2.7.0
 craft-grammar==2.0.1

requirements.txt

@@ -7,7 +7,7 @@ cffi==1.17.1
 chardet==5.2.0
 charset-normalizer==3.3.2
 click==8.1.7
-craft-application==4.2.3
+craft-application==4.2.4
 craft-archives==2.0.0
 craft-cli==2.7.0
 craft-grammar==2.0.1

setup.py

@@ -98,7 +98,7 @@ def recursive_data_files(directory, install_directory):
     "attrs",
     "catkin-pkg; sys_platform == 'linux'",
     "click",
-    "craft-application~=4.1",
+    "craft-application>=4.2.4,<5.0.0",
     "craft-archives~=2.0",
     "craft-cli~=2.6",
     "craft-grammar>=2.0.1,<3.0.0",

snapcraft/application.py

@@ -27,7 +27,7 @@
 import craft_cli
 import craft_parts
 import craft_store
-from craft_application import Application, AppMetadata, util
+from craft_application import Application, AppMetadata, remote, util
 from craft_application.commands import get_other_command_group
 from craft_cli import emit
 from craft_parts.plugins.plugins import PluginType
@@ -82,6 +82,7 @@ def _get_esm_error_for_base(base: str) -> None:
             f"Use Snapcraft {version} from the {channel!r} channel of snapcraft where "
             f"{base!r} was last supported."
         ),
+        doc_slug="/reference/bases",
     )
 
 
@@ -231,6 +232,10 @@ def _run_inner(self) -> int:
                 cause=err,
             )
             return_code = 1
+        except remote.RemoteBuildError as err:
+            err.doc_slug = "/explanation/remote-build"
+            self._emit_error(err)
+            return_code = err.retcode
 
         return return_code
 
@@ -391,6 +396,7 @@ def _ensure_remote_build_supported(base: str) -> None:
                 resolution=(
                     "Valid values are 'disable-fallback' and 'force-fallback'."
                 ),
+                doc_slug="/explanation/remote-build",
             )
 
         # 2. core20 projects must use the legacy remote builder (#4885)
@@ -403,6 +409,7 @@ def _ensure_remote_build_supported(base: str) -> None:
                 resolution=(
                     "Unset the environment variable or set it to 'force-fallback'."
                 ),
+                doc_slug="/explanation/remote-build",
             )
 
         # 3. core24 and newer projects must use the craft-application remote builder
@@ -415,6 +422,7 @@ def _ensure_remote_build_supported(base: str) -> None:
                 resolution=(
                     "Unset the environment variable or set it to 'disable-fallback'."
                 ),
+                doc_slug="/explanation/remote-build",
             )
 
     @override

tests/unit/test_application.py

@@ -17,9 +17,11 @@
 
 import json
 import os
+import re
 import sys
 from textwrap import dedent
 
+import craft_application.remote
 import craft_cli
 import craft_parts.plugins
 import craft_store
@@ -398,7 +400,13 @@ def test_esm_error(snapcraft_yaml, base, monkeypatch, capsys):
     application.main()
 
     _, err = capsys.readouterr()
-    assert f"Base {base!r} is not supported by this version of Snapcraft" in err
+
+    assert re.match(
+        rf"^Base {base!r} is not supported by this version of Snapcraft.\n"
+        rf"Recommended resolution: Use Snapcraft .* from the '.*' channel of snapcraft where {base!r} was last supported.\n"
+        r"For more information, check out: .*/reference/bases\n",
+        err,
+    )
 
 
 @pytest.mark.parametrize("base", const.CURRENT_BASES)
@@ -459,10 +467,12 @@ def test_run_remote_build_core24_error(monkeypatch, snapcraft_yaml, base, capsys
     application.main()
 
     _, err = capsys.readouterr()
-    assert (
-        "'SNAPCRAFT_REMOTE_BUILD_STRATEGY=force-fallback' cannot be used "
-        "for core24 and newer snaps"
-    ) in err
+    assert re.match(
+        r"^'SNAPCRAFT_REMOTE_BUILD_STRATEGY=force-fallback' cannot be used for core24 and newer snaps\.\n"
+        r"Recommended resolution: Unset the environment variable or set it to 'disable-fallback'\.\n"
+        r"For more information, check out: .*/explanation/remote-build",
+        err,
+    )
 
 
 @pytest.mark.parametrize("base", const.LEGACY_BASES)
@@ -477,9 +487,11 @@ def test_run_envvar_disable_fallback_core20(snapcraft_yaml, base, monkeypatch, c
     application.main()
 
     _, err = capsys.readouterr()
-    assert (
-        f"'SNAPCRAFT_REMOTE_BUILD_STRATEGY=disable-fallback' cannot be used for {base} snaps"
-        in err
+    assert re.match(
+        r"'SNAPCRAFT_REMOTE_BUILD_STRATEGY=disable-fallback' cannot be used for core20 snaps\.\n"
+        r"Recommended resolution: Unset the environment variable or set it to 'force-fallback'\.\n"
+        r"For more information, check out: .*/explanation/remote-build",
+        err,
     )
 
 
@@ -544,9 +556,11 @@ def test_run_envvar_invalid(snapcraft_yaml, base, monkeypatch, capsys):
     application.main()
 
     _, err = capsys.readouterr()
-    assert (
-        "Unknown value 'badvalue' in environment variable 'SNAPCRAFT_REMOTE_BUILD_STRATEGY'"
-        in err
+    assert re.match(
+        r"Unknown value 'badvalue' in environment variable 'SNAPCRAFT_REMOTE_BUILD_STRATEGY'\.\n"
+        r"Recommended resolution: Valid values are 'disable-fallback' and 'force-fallback'\.\n"
+        r"For more information, check out: .*/explanation/remote-build",
+        err,
     )
 
 
@@ -701,6 +715,25 @@ def test_store_key_error(mocker, capsys):
     )
 
 
+def test_remote_build_error(mocker, capsys):
+    """Catch remote build errors and include a documentation link."""
+    mocker.patch(
+        "snapcraft.application.Application._run_inner",
+        side_effect=craft_application.remote.RemoteBuildError(message="test-error"),
+    )
+
+    return_code = application.main()
+
+    assert return_code == 1
+    _, err = capsys.readouterr()
+
+    assert re.match(
+        r"^test-error\n"
+        r"For more information, check out: .*/explanation/remote-build\n",
+        err,
+    )
+
+
 @pytest.mark.parametrize(
     "command",
     {