Skip to content

Errors

Exceptions.

Error

Bases: Exception

Base sigstore exception type. Defines helpers for diagnostics.

diagnostics()

Returns human-friendly error information.

Source code in sigstore/errors.py
29
30
31
32
def diagnostics(self) -> str:
    """Returns human-friendly error information."""

    return str(self)

log_and_exit(logger, raise_error=False)

Prints all relevant error information to stderr and exits.

Source code in sigstore/errors.py
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
def log_and_exit(self, logger: Logger, raise_error: bool = False) -> NoReturn:
    """Prints all relevant error information to stderr and exits."""

    remind_verbose = (
        "Raising original exception:"
        if raise_error
        else "For detailed error information, run sigstore with the `--verbose` flag."
    )

    logger.error(f"{self.diagnostics()}\n{remind_verbose}")

    if raise_error:
        # don't want "during handling another exception"
        self.__suppress_context__ = True
        raise self

    sys.exit(1)

NetworkError

Bases: Error

Raised when a connectivity-related issue occurs.

diagnostics()

Returns diagnostics for the error.

Source code in sigstore/errors.py
56
57
58
def diagnostics(self) -> str:
    """Returns diagnostics for the error."""
    return self._diagnostics(str(self.__cause__))

TUFError(message)

Bases: Error

Raised when a TUF error occurs.

Constructs a TUFError.

Source code in sigstore/errors.py
73
74
75
76
def __init__(self, message: str):
    """Constructs a `TUFError`."""
    super().__init__(message)
    self.message = message

diagnostics()

Returns diagnostics specialized to the wrapped TUF error.

Source code in sigstore/errors.py
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
def diagnostics(self) -> str:
    """Returns diagnostics specialized to the wrapped TUF error."""
    # Download errors are likely to be ephemeral: just use NetworkError output
    if isinstance(self.__cause__, exceptions.DownloadError):
        return NetworkError._diagnostics(f"{self.message}: {self.__cause__}")

    # Other TUF errors are likely to be cryptic and unrecoverable
    cause_ctx = (
        f"\n\nAdditional context:\n\n{self.__cause__}" if self.__cause__ else ""
    )
    return (
        f"{self.message}.\n\n"
        "Please check any Sigstore instance related arguments and consider "
        "reporting the issue at <https://github.com/sigstore/sigstore-python/issues/new>."
        + cause_ctx
    )

MetadataError

Bases: Error

Raised when TUF metadata does not conform to the expected structure.

diagnostics()

Returns diagnostics for the error.

Source code in sigstore/errors.py
 99
100
101
def diagnostics(self) -> str:
    """Returns diagnostics for the error."""
    return f"""{self}."""

RootError

Bases: Error

Raised when TUF cannot establish its root of trust.

diagnostics()

Returns diagnostics for the error.

Source code in sigstore/errors.py
107
108
109
110
111
112
113
def diagnostics(self) -> str:
    """Returns diagnostics for the error."""
    return (
        "Unable to establish root of trust.\n\n"
        "This error may occur when the resources embedded in this "
        "distribution of sigstore-python are out of date."
    )

VerificationError

Bases: Error

Raised whenever any phase or subcomponent of Sigstore verification fails.

CertValidationError

Bases: VerificationError

Raised when a TSA certificate chain fails to validate during Sigstore verification.

This is used by CLI to hint that an incorrect Sigstore instance may have been used