{"id":13621231,"url":"https://github.com/juju/errors","last_synced_at":"2025-05-14T01:04:08.288Z","repository":{"id":16835770,"uuid":"19595279","full_name":"juju/errors","owner":"juju","description":"Common juju errors and functions to annotate errors.  Based on juju/errgo","archived":false,"fork":false,"pushed_at":"2023-10-23T23:58:07.000Z","size":152,"stargazers_count":1395,"open_issues_count":3,"forks_count":81,"subscribers_count":44,"default_branch":"v1","last_synced_at":"2025-04-03T01:31:29.928Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/juju.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2014-05-09T01:49:22.000Z","updated_at":"2025-03-15T16:45:17.000Z","dependencies_parsed_at":"2024-01-13T23:01:21.495Z","dependency_job_id":"fd6ed019-4fd0-4739-ac1f-3405056587f9","html_url":"https://github.com/juju/errors","commit_stats":{"total_commits":91,"total_committers":28,"mean_commits":3.25,"dds":0.6813186813186813,"last_synced_commit":"54a94488269b924b361ff837cd38e75fb507e48c"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juju%2Ferrors","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juju%2Ferrors/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juju%2Ferrors/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juju%2Ferrors/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/juju","download_url":"https://codeload.github.com/juju/errors/tar.gz/refs/heads/v1","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248154425,"owners_count":21056538,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T21:01:03.818Z","updated_at":"2025-04-10T03:39:34.728Z","avatar_url":"https://github.com/juju.png","language":"Go","funding_links":[],"categories":["Misc","开源类库","Go","Open source library"],"sub_categories":["错误处理","Error Handling"],"readme":"\n# errors\n    import \"github.com/juju/errors\"\n\n[![GoDoc](https://godoc.org/github.com/juju/errors?status.svg)](https://godoc.org/github.com/juju/errors)\n\nThe juju/errors provides an easy way to annotate errors without losing the\noriginal error context.\n\nThe exported `New` and `Errorf` functions are designed to replace the\n`errors.New` and `fmt.Errorf` functions respectively. The same underlying\nerror is there, but the package also records the location at which the error\nwas created.\n\nA primary use case for this library is to add extra context any time an\nerror is returned from a function.\n\n\n\t    if err := SomeFunc(); err != nil {\n\t\t    return err\n\t\t}\n\nThis instead becomes:\n\n\n\t    if err := SomeFunc(); err != nil {\n\t\t    return errors.Trace(err)\n\t\t}\n\nwhich just records the file and line number of the Trace call, or\n\n\n\t    if err := SomeFunc(); err != nil {\n\t\t    return errors.Annotate(err, \"more context\")\n\t\t}\n\nwhich also adds an annotation to the error.\n\nWhen you want to check to see if an error is of a particular type, a helper\nfunction is normally exported by the package that returned the error, like the\n`os` package does.  The underlying cause of the error is available using the\n`Cause` function.\n\n\n\tos.IsNotExist(errors.Cause(err))\n\nThe result of the `Error()` call on an annotated error is the annotations joined\nwith colons, then the result of the `Error()` method for the underlying error\nthat was the cause.\n\n\n\terr := errors.Errorf(\"original\")\n\terr = errors.Annotatef(err, \"context\")\n\terr = errors.Annotatef(err, \"more context\")\n\terr.Error() -\u003e \"more context: context: original\"\n\nObviously recording the file, line and functions is not very useful if you\ncannot get them back out again.\n\n\n\terrors.ErrorStack(err)\n\nwill return something like:\n\n\n\tfirst error\n\tgithub.com/juju/errors/annotation_test.go:193:\n\tgithub.com/juju/errors/annotation_test.go:194: annotation\n\tgithub.com/juju/errors/annotation_test.go:195:\n\tgithub.com/juju/errors/annotation_test.go:196: more context\n\tgithub.com/juju/errors/annotation_test.go:197:\n\nThe first error was generated by an external system, so there was no location\nassociated. The second, fourth, and last lines were generated with Trace calls,\nand the other two through Annotate.\n\nSometimes when responding to an error you want to return a more specific error\nfor the situation.\n\n\n\t    if err := FindField(field); err != nil {\n\t\t    return errors.Wrap(err, errors.NotFoundf(field))\n\t\t}\n\nThis returns an error where the complete error stack is still available, and\n`errors.Cause()` will return the `NotFound` error.\n\n\n\n\n\n\n## func AlreadyExistsf\n``` go\nfunc AlreadyExistsf(format string, args ...interface{}) error\n```\nAlreadyExistsf returns an error which satisfies IsAlreadyExists().\n\n\n## func Annotate\n``` go\nfunc Annotate(other error, message string) error\n```\nAnnotate is used to add extra context to an existing error. The location of\nthe Annotate call is recorded with the annotations. The file, line and\nfunction are also recorded.\n\nFor example:\n\n\n\tif err := SomeFunc(); err != nil {\n\t    return errors.Annotate(err, \"failed to frombulate\")\n\t}\n\n\n## func Annotatef\n``` go\nfunc Annotatef(other error, format string, args ...interface{}) error\n```\nAnnotatef is used to add extra context to an existing error. The location of\nthe Annotate call is recorded with the annotations. The file, line and\nfunction are also recorded.\n\nFor example:\n\n\n\tif err := SomeFunc(); err != nil {\n\t    return errors.Annotatef(err, \"failed to frombulate the %s\", arg)\n\t}\n\n\n## func BadRequestf\n``` go\nfunc BadRequestf(format string, args ...interface{}) error\n```\nBadRequestf returns an error which satisfies IsBadRequest().\n\n\n## func Cause\n``` go\nfunc Cause(err error) error\n```\nCause returns the cause of the given error.  This will be either the\noriginal error, or the result of a Wrap or Mask call.\n\nCause is the usual way to diagnose errors that may have been wrapped by\nthe other errors functions.\n\n\n## func DeferredAnnotatef\n``` go\nfunc DeferredAnnotatef(err *error, format string, args ...interface{})\n```\nDeferredAnnotatef annotates the given error (when it is not nil) with the given\nformat string and arguments (like fmt.Sprintf). If *err is nil, DeferredAnnotatef\ndoes nothing. This method is used in a defer statement in order to annotate any\nresulting error with the same message.\n\nFor example:\n\n\n\tdefer DeferredAnnotatef(\u0026err, \"failed to frombulate the %s\", arg)\n\n\n## func Details\n``` go\nfunc Details(err error) string\n```\nDetails returns information about the stack of errors wrapped by err, in\nthe format:\n\n\n\t[{filename:99: error one} {otherfile:55: cause of error one}]\n\nThis is a terse alternative to ErrorStack as it returns a single line.\n\n\n## func ErrorStack\n``` go\nfunc ErrorStack(err error) string\n```\nErrorStack returns a string representation of the annotated error. If the\nerror passed as the parameter is not an annotated error, the result is\nsimply the result of the Error() method on that error.\n\nIf the error is an annotated error, a multi-line string is returned where\neach line represents one entry in the annotation stack. The full filename\nfrom the call stack is used in the output.\n\n\n\tfirst error\n\tgithub.com/juju/errors/annotation_test.go:193:\n\tgithub.com/juju/errors/annotation_test.go:194: annotation\n\tgithub.com/juju/errors/annotation_test.go:195:\n\tgithub.com/juju/errors/annotation_test.go:196: more context\n\tgithub.com/juju/errors/annotation_test.go:197:\n\n\n## func Errorf\n``` go\nfunc Errorf(format string, args ...interface{}) error\n```\nErrorf creates a new annotated error and records the location that the\nerror is created.  This should be a drop in replacement for fmt.Errorf.\n\nFor example:\n\n\n\treturn errors.Errorf(\"validation failed: %s\", message)\n\n\n## func Forbiddenf\n``` go\nfunc Forbiddenf(format string, args ...interface{}) error\n```\nForbiddenf returns an error which satistifes IsForbidden()\n\n\n## func IsAlreadyExists\n``` go\nfunc IsAlreadyExists(err error) bool\n```\nIsAlreadyExists reports whether the error was created with\nAlreadyExistsf() or NewAlreadyExists().\n\n\n## func IsBadRequest\n``` go\nfunc IsBadRequest(err error) bool\n```\nIsBadRequest reports whether err was created with BadRequestf() or\nNewBadRequest().\n\n\n## func IsForbidden\n``` go\nfunc IsForbidden(err error) bool\n```\nIsForbidden reports whether err was created with Forbiddenf() or\nNewForbidden().\n\n\n## func IsMethodNotAllowed\n``` go\nfunc IsMethodNotAllowed(err error) bool\n```\nIsMethodNotAllowed reports whether err was created with MethodNotAllowedf() or\nNewMethodNotAllowed().\n\n\n## func IsNotAssigned\n``` go\nfunc IsNotAssigned(err error) bool\n```\nIsNotAssigned reports whether err was created with NotAssignedf() or\nNewNotAssigned().\n\n\n## func IsNotFound\n``` go\nfunc IsNotFound(err error) bool\n```\nIsNotFound reports whether err was created with NotFoundf() or\nNewNotFound().\n\n\n## func IsNotImplemented\n``` go\nfunc IsNotImplemented(err error) bool\n```\nIsNotImplemented reports whether err was created with\nNotImplementedf() or NewNotImplemented().\n\n\n## func IsNotProvisioned\n``` go\nfunc IsNotProvisioned(err error) bool\n```\nIsNotProvisioned reports whether err was created with NotProvisionedf() or\nNewNotProvisioned().\n\n\n## func IsNotSupported\n``` go\nfunc IsNotSupported(err error) bool\n```\nIsNotSupported reports whether the error was created with\nNotSupportedf() or NewNotSupported().\n\n\n## func IsNotValid\n``` go\nfunc IsNotValid(err error) bool\n```\nIsNotValid reports whether the error was created with NotValidf() or\nNewNotValid().\n\n\n## func IsUnauthorized\n``` go\nfunc IsUnauthorized(err error) bool\n```\nIsUnauthorized reports whether err was created with Unauthorizedf() or\nNewUnauthorized().\n\n\n## func IsUserNotFound\n``` go\nfunc IsUserNotFound(err error) bool\n```\nIsUserNotFound reports whether err was created with UserNotFoundf() or\nNewUserNotFound().\n\n\n## func Mask\n``` go\nfunc Mask(other error) error\n```\nMask hides the underlying error type, and records the location of the masking.\n\n\n## func Maskf\n``` go\nfunc Maskf(other error, format string, args ...interface{}) error\n```\nMask masks the given error with the given format string and arguments (like\nfmt.Sprintf), returning a new error that maintains the error stack, but\nhides the underlying error type.  The error string still contains the full\nannotations. If you want to hide the annotations, call Wrap.\n\n\n## func MethodNotAllowedf\n``` go\nfunc MethodNotAllowedf(format string, args ...interface{}) error\n```\nMethodNotAllowedf returns an error which satisfies IsMethodNotAllowed().\n\n\n## func New\n``` go\nfunc New(message string) error\n```\nNew is a drop in replacement for the standard library errors module that records\nthe location that the error is created.\n\nFor example:\n\n\n\treturn errors.New(\"validation failed\")\n\n\n## func NewAlreadyExists\n``` go\nfunc NewAlreadyExists(err error, msg string) error\n```\nNewAlreadyExists returns an error which wraps err and satisfies\nIsAlreadyExists().\n\n\n## func NewBadRequest\n``` go\nfunc NewBadRequest(err error, msg string) error\n```\nNewBadRequest returns an error which wraps err that satisfies\nIsBadRequest().\n\n\n## func NewForbidden\n``` go\nfunc NewForbidden(err error, msg string) error\n```\nNewForbidden returns an error which wraps err that satisfies\nIsForbidden().\n\n\n## func NewMethodNotAllowed\n``` go\nfunc NewMethodNotAllowed(err error, msg string) error\n```\nNewMethodNotAllowed returns an error which wraps err that satisfies\nIsMethodNotAllowed().\n\n\n## func NewNotAssigned\n``` go\nfunc NewNotAssigned(err error, msg string) error\n```\nNewNotAssigned returns an error which wraps err that satisfies\nIsNotAssigned().\n\n\n## func NewNotFound\n``` go\nfunc NewNotFound(err error, msg string) error\n```\nNewNotFound returns an error which wraps err that satisfies\nIsNotFound().\n\n\n## func NewNotImplemented\n``` go\nfunc NewNotImplemented(err error, msg string) error\n```\nNewNotImplemented returns an error which wraps err and satisfies\nIsNotImplemented().\n\n\n## func NewNotProvisioned\n``` go\nfunc NewNotProvisioned(err error, msg string) error\n```\nNewNotProvisioned returns an error which wraps err that satisfies\nIsNotProvisioned().\n\n\n## func NewNotSupported\n``` go\nfunc NewNotSupported(err error, msg string) error\n```\nNewNotSupported returns an error which wraps err and satisfies\nIsNotSupported().\n\n\n## func NewNotValid\n``` go\nfunc NewNotValid(err error, msg string) error\n```\nNewNotValid returns an error which wraps err and satisfies IsNotValid().\n\n\n## func NewUnauthorized\n``` go\nfunc NewUnauthorized(err error, msg string) error\n```\nNewUnauthorized returns an error which wraps err and satisfies\nIsUnauthorized().\n\n\n## func NewUserNotFound\n``` go\nfunc NewUserNotFound(err error, msg string) error\n```\nNewUserNotFound returns an error which wraps err and satisfies\nIsUserNotFound().\n\n\n## func NotAssignedf\n``` go\nfunc NotAssignedf(format string, args ...interface{}) error\n```\nNotAssignedf returns an error which satisfies IsNotAssigned().\n\n\n## func NotFoundf\n``` go\nfunc NotFoundf(format string, args ...interface{}) error\n```\nNotFoundf returns an error which satisfies IsNotFound().\n\n\n## func NotImplementedf\n``` go\nfunc NotImplementedf(format string, args ...interface{}) error\n```\nNotImplementedf returns an error which satisfies IsNotImplemented().\n\n\n## func NotProvisionedf\n``` go\nfunc NotProvisionedf(format string, args ...interface{}) error\n```\nNotProvisionedf returns an error which satisfies IsNotProvisioned().\n\n\n## func NotSupportedf\n``` go\nfunc NotSupportedf(format string, args ...interface{}) error\n```\nNotSupportedf returns an error which satisfies IsNotSupported().\n\n\n## func NotValidf\n``` go\nfunc NotValidf(format string, args ...interface{}) error\n```\nNotValidf returns an error which satisfies IsNotValid().\n\n\n## func Trace\n``` go\nfunc Trace(other error) error\n```\nTrace adds the location of the Trace call to the stack.  The Cause of the\nresulting error is the same as the error parameter.  If the other error is\nnil, the result will be nil.\n\nFor example:\n\n\n\tif err := SomeFunc(); err != nil {\n\t    return errors.Trace(err)\n\t}\n\n\n## func Unauthorizedf\n``` go\nfunc Unauthorizedf(format string, args ...interface{}) error\n```\nUnauthorizedf returns an error which satisfies IsUnauthorized().\n\n\n## func UserNotFoundf\n``` go\nfunc UserNotFoundf(format string, args ...interface{}) error\n```\nUserNotFoundf returns an error which satisfies IsUserNotFound().\n\n\n## func Wrap\n``` go\nfunc Wrap(other, newDescriptive error) error\n```\nWrap changes the Cause of the error. The location of the Wrap call is also\nstored in the error stack.\n\nFor example:\n\n\n\tif err := SomeFunc(); err != nil {\n\t    newErr := \u0026packageError{\"more context\", private_value}\n\t    return errors.Wrap(err, newErr)\n\t}\n\n\n## func Wrapf\n``` go\nfunc Wrapf(other, newDescriptive error, format string, args ...interface{}) error\n```\nWrapf changes the Cause of the error, and adds an annotation. The location\nof the Wrap call is also stored in the error stack.\n\nFor example:\n\n\n\tif err := SomeFunc(); err != nil {\n\t    return errors.Wrapf(err, simpleErrorType, \"invalid value %q\", value)\n\t}\n\n\n\n## type Err\n``` go\ntype Err struct {\n    // contains filtered or unexported fields\n}\n```\nErr holds a description of an error along with information about\nwhere the error was created.\n\nIt may be embedded in custom error types to add extra information that\nthis errors package can understand.\n\n\n\n\n\n\n\n\n\n### func NewErr\n``` go\nfunc NewErr(format string, args ...interface{}) Err\n```\nNewErr is used to return an Err for the purpose of embedding in other\nstructures.  The location is not specified, and needs to be set with a call\nto SetLocation.\n\nFor example:\n\n\n\ttype FooError struct {\n\t    errors.Err\n\t    code int\n\t}\n\t\n\tfunc NewFooError(code int) error {\n\t    err := \u0026FooError{errors.NewErr(\"foo\"), code}\n\t    err.SetLocation(1)\n\t    return err\n\t}\n\n\n### func NewErrWithCause\n``` go\nfunc NewErrWithCause(other error, format string, args ...interface{}) Err\n```\nNewErrWithCause is used to return an Err with cause by other error for the purpose of embedding in other\nstructures. The location is not specified, and needs to be set with a call\nto SetLocation.\n\nFor example:\n\n\n\ttype FooError struct {\n\t    errors.Err\n\t    code int\n\t}\n\t\n\tfunc (e *FooError) Annotate(format string, args ...interface{}) error {\n\t    err := \u0026FooError{errors.NewErrWithCause(e.Err, format, args...), e.code}\n\t    err.SetLocation(1)\n\t    return err\n\t})\n\n\n\n\n### func (\\*Err) Cause\n``` go\nfunc (e *Err) Cause() error\n```\nThe Cause of an error is the most recent error in the error stack that\nmeets one of these criteria: the original error that was raised; the new\nerror that was passed into the Wrap function; the most recently masked\nerror; or nil if the error itself is considered the Cause.  Normally this\nmethod is not invoked directly, but instead through the Cause stand alone\nfunction.\n\n\n\n### func (\\*Err) Error\n``` go\nfunc (e *Err) Error() string\n```\nError implements error.Error.\n\n\n\n### func (\\*Err) Format\n``` go\nfunc (e *Err) Format(s fmt.State, verb rune)\n```\nFormat implements fmt.Formatter\nWhen printing errors with %+v it also prints the stack trace.\n%#v unsurprisingly will print the real underlying type.\n\n\n\n### func (\\*Err) Location\n``` go\nfunc (e *Err) Location() (filename string, line int)\n```\nLocation is the file and line of where the error was most recently\ncreated or annotated.\n\n\n\n### func (\\*Err) Message\n``` go\nfunc (e *Err) Message() string\n```\nMessage returns the message stored with the most recent location. This is\nthe empty string if the most recent call was Trace, or the message stored\nwith Annotate or Mask.\n\n\n\n### func (\\*Err) SetLocation\n``` go\nfunc (e *Err) SetLocation(callDepth int)\n```\nSetLocation records the source location of the error at callDepth stack\nframes above the call.\n\n\n\n### func (\\*Err) StackTrace\n``` go\nfunc (e *Err) StackTrace() []string\n```\nStackTrace returns one string for each location recorded in the stack of\nerrors. The first value is the originating error, with a line for each\nother annotation or tracing of the error.\n\n\n\n### func (\\*Err) Underlying\n``` go\nfunc (e *Err) Underlying() error\n```\nUnderlying returns the previous error in the error stack, if any. A client\nshould not ever really call this method.  It is used to build the error\nstack and should not be introspected by client calls.  Or more\nspecifically, clients should not depend on anything but the `Cause` of an\nerror.\n\n\n\n\n\n\n\n\n\n- - -\nGenerated by [godoc2md](http://godoc.org/github.com/davecheney/godoc2md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuju%2Ferrors","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjuju%2Ferrors","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuju%2Ferrors/lists"}