From bd4c06031bad1896d60e44fd5a979d73d1208bc9 Mon Sep 17 00:00:00 2001 From: Nomee Singh Date: Wed, 9 Sep 2026 22:10:12 +0530 Subject: [PATCH 1/2] docs: add installation troubleshooting guide Signed-off-by: Nomee Singh --- README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/README.md b/README.md index 6a5b9b4..60ffcad 100644 --- a/README.md +++ b/README.md @@ -124,6 +124,50 @@ The action supports x86_64 and ARM64 Linux, x86_64 and ARM64 macOS, and x86_64 W [SECURITY.md](https://github.com/getsotto/sotto/blob/main/SECURITY.md) for Sotto's release and verification model. +## Troubleshooting + +If installation fails, check the error message below for the likely cause and the next steps. + +### + +The CLI version must be an exact release in format, such as . Passing the format check does not confirm that the release exists. + +Check the [Sotto releases](https://github.com/getsotto/sotto/releases) page and use an exact release tag. + +### + +The requested release or the required asset for the runner's operating system and architecture could not be found. + +Check that the requested CLI release exists and that it provides an asset for the runner target. + +### + +The installer could not download the requested file. + +Inspect the failed URL in the runner logs and check the runner's network connectivity, proxy, or firewall configuration. This is different from a missing release asset. + +### + +The downloaded file or checksum manifest could not be successfully verified using Sigstore. + +Inspect the failed verification step and its logs. If the failure persists, report the action ref, Sotto CLI version, runner, and relevant logs. Do not disable verification. + +### + +The downloaded file's SHA-256 checksum does not match the expected checksum in . + +Inspect the checksum verification step and its logs. If the failure persists, report the action ref, Sotto CLI version, runner, and relevant logs. + +### + +No prebuilt Sotto binary is available for the runner's operating system and architecture. On Windows, the error includes the architecture. + +Check the [Security model](#security-model) for supported platforms and confirm that the runner's operating system and architecture are supported. + +When reporting a persistent installation problem, include the relevant error message and logs, but remove tokens, secrets, and other sensitive information before sharing them. + +For unresolved problems, open an issue in the [Sotto Action repository](https://github.com/getsotto/sotto-action/issues). + ## Examples ### Linux, macOS, and Windows matrix From 3376c61e5745306cf14b77ad541d63f4d60ee63a Mon Sep 17 00:00:00 2001 From: Nomee Singh Date: Thu, 10 Sep 2026 17:47:52 +0530 Subject: [PATCH 2/2] docs: restore installer error messages Signed-off-by: Nomee Singh --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 60ffcad..6243d54 100644 --- a/README.md +++ b/README.md @@ -128,37 +128,37 @@ verification model. If installation fails, check the error message below for the likely cause and the next steps. -### +### `sotto-version must be an exact release such as v0.4.0` -The CLI version must be an exact release in format, such as . Passing the format check does not confirm that the release exists. +The CLI version must be an exact release in `vX.Y.Z` format, such as `v0.4.0`. Passing the format check does not confirm that the release exists. Check the [Sotto releases](https://github.com/getsotto/sotto/releases) page and use an exact release tag. -### +### `release asset not found: $1` / `release asset not found: $Uri` The requested release or the required asset for the runner's operating system and architecture could not be found. Check that the requested CLI release exists and that it provides an asset for the runner target. -### +### `download failed: $1` / `download failed: $Uri` The installer could not download the requested file. Inspect the failed URL in the runner logs and check the runner's network connectivity, proxy, or firewall configuration. This is different from a missing release asset. -### +### `Sigstore verification failed for $file` / `Sigstore verification failed for $Asset` / `Sigstore verification failed for SHA256SUMS` The downloaded file or checksum manifest could not be successfully verified using Sigstore. Inspect the failed verification step and its logs. If the failure persists, report the action ref, Sotto CLI version, runner, and relevant logs. Do not disable verification. -### +### `checksum verification failed for $asset` / `checksum verification failed for $Asset` -The downloaded file's SHA-256 checksum does not match the expected checksum in . +The downloaded file's SHA-256 checksum does not match the expected checksum in `SHA256SUMS`. Inspect the checksum verification step and its logs. If the failure persists, report the action ref, Sotto CLI version, runner, and relevant logs. -### +### `no prebuilt Sotto binary for $os/$arch` / `no prebuilt Sotto binary for Windows/$Architecture` No prebuilt Sotto binary is available for the runner's operating system and architecture. On Windows, the error includes the architecture.