Skip to content

docs: add installation troubleshooting guide #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Maxerns merged 2 commits into from
Sep 10, 2026
Merged

docs: add installation troubleshooting guide #21

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bd4c060
docs: add installation troubleshooting guide
Nomee-123 Sep 9, 2026
3376c61
docs: restore installer error messages
Nomee-123 Sep 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

### `sotto-version must be an exact release such as v0.4.0`

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 `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.

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
Expand Down
Loading