Skip to content

README: Add a Troubleshooting section #1689

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

Open
jku wants to merge 3 commits into
base: main
Choose a base branch
from
Open

README: Add a Troubleshooting section #1689

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f914d02
README: Add a Troubleshooting section
jku Feb 12, 2026
1012dcb
README: mention a more obscure error as well
jku Feb 12, 2026
28a964c
README: link to offline docs
jku Feb 12, 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
27 changes: 27 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ else!
* [Generic identities](#generic-identities)
* [Signatures from GitHub Actions](#signatures-from-github-actions)
* [Advanced usage](#advanced-usage)
* [Troubleshooting](#troubleshooting)
* [Documentation](#documentation)
* [Licensing](#licensing)
* [Community](#community)
Expand Down Expand Up @@ -302,6 +303,32 @@ Verification options:
```
<!-- @end-sigstore-verify-github-help@ -->

## Troubleshooting

First, please make sure you are using a recent and supported release:
sigstore-python project provides support for the latest release and
best effort critical bug fixes for the latest 3.6.x release.

### Common issues

1. "_bundle contains a transparency log entry that is incompatible with
this version of sigstore-python_" (as well as "_not enough sources of
verified time_") means an upgrade is necessary to verify this signature
bundle: Signature bundles with Rekor v2 transparency log entries can only be
verified with sigstore-python 4 and above
1. verifying without a network connection results in HTTP errors: By default
sigstore-python checks for updates to the trusted key material on every
startup. This can be avoided temporarily with `--offline` but please read the
[documentation](https://sigstore.github.io/sigstore-python/advanced/offline/)
for caveats
1. Signing results in HTTP errors: Signing with sigstore-python depends on multiple
Sigstore services. Retrying on failure may be a useful workaround if any of
these services fail but filing issues for specific failures is appreciated

### My problem is something else

Please [open an issue](https://github.com/sigstore/sigstore-python/issues/new?template=bug.md) or ask in the [slack channel](#community).

## Documentation

`sigstore` documentation is available on [https://sigstore.github.io/sigstore-python](https://sigstore.github.io/sigstore-python)
Expand Down