v1.37.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: May 10, 2024 License: MPL-2.0 Imports: 2 Imported by: 4



Package errs provides structured error handling for Encore applications.

See for more information about how errors work within Encore applications.



This section is empty.


This section is empty.


func Convert added in v0.13.1

func Convert(err error) (_ error)

Convert converts an error to an *Error. If the error is already an *Error it returns it unmodified. If err is nil it returns nil.

func HTTPError

func HTTPError(w http.ResponseWriter, err error)

HTTPError writes structured error information to w using JSON encoding. The status code is computed with HTTPStatus.

If err is nil it writes:

{"code": "ok", "message": "", "details": null}

func Wrap

func Wrap(err error, msg string, metaPairs ...interface{}) (_ error)

Wrap wraps the err, adding additional error information. If err is nil it returns nil.

If err is already an *Error its code, message, and details are copied over to the new error.

func WrapCode added in v0.13.1

func WrapCode(err error, code ErrCode, msg string, metaPairs ...interface{}) (_ error)

WrapCode is like Wrap but also sets the error code. If code is OK it reports nil.


type Builder added in v0.13.1

type Builder struct {
	// contains filtered or unexported fields

A Builder allows for gradual construction of an error. The zero value is ready for use.

Use Err() to construct the error.

func B added in v0.13.1

func B() (_ *Builder)

B is a shorthand for creating a new Builder.

func (*Builder) Cause added in v0.13.1

func (*Builder) Cause(err error) (_ *Builder)

Cause sets the underlying error cause.

func (*Builder) Code added in v0.13.1

func (*Builder) Code(c ErrCode) (_ *Builder)

Code sets the error code.

func (*Builder) Details added in v0.13.1

func (*Builder) Details(det ErrDetails) (_ *Builder)

Details sets the details.

func (*Builder) Err added in v0.13.1

func (*Builder) Err() (_ error)

Err returns the constructed error. It never returns nil.

If Code has not been set or has been set to OK, the Code is set to Unknown.

If Msg has not been set and Cause is nil, the Msg is set to "unknown error".

func (*Builder) Meta added in v0.13.1

func (*Builder) Meta(metaPairs ...interface{}) (_ *Builder)

Meta appends metadata key-value pairs.

func (*Builder) Msg added in v0.13.1

func (*Builder) Msg(msg string) (_ *Builder)

Msg sets the error message.

func (*Builder) Msgf added in v0.13.1

func (*Builder) Msgf(format string, args ...interface{}) (_ *Builder)

Msgf is like Msg but uses fmt.Sprintf to construct the message.

type ErrCode

type ErrCode int

ErrCode is an RPC error code.

const (
	// OK indicates the operation was successful.
	OK ErrCode = 0

	// Canceled indicates the operation was canceled (typically by the caller).
	// Encore will generate this error code when cancellation is requested.
	Canceled ErrCode = 1

	// Unknown error. An example of where this error may be returned is
	// if a Status value received from another address space belongs to
	// an error-space that is not known in this address space. Also
	// errors raised by APIs that do not return enough error information
	// may be converted to this error.
	// Encore will generate this error code in the above two mentioned cases.
	Unknown ErrCode = 2

	// InvalidArgument indicates client specified an invalid argument.
	// Note that this differs from FailedPrecondition. It indicates arguments
	// that are problematic regardless of the state of the system
	// (e.g., a malformed file name).
	// Encore will generate this error code if the request data cannot be parsed.
	InvalidArgument ErrCode = 3

	// DeadlineExceeded means operation expired before completion.
	// For operations that change the state of the system, this error may be
	// returned even if the operation has completed successfully. For
	// example, a successful response from a server could have been delayed
	// long enough for the deadline to expire.
	// Encore will generate this error code when the deadline is exceeded.
	DeadlineExceeded ErrCode = 4

	// NotFound means some requested entity (e.g., file or directory) was
	// not found.
	// Encore will not generate this error code.
	NotFound ErrCode = 5

	// AlreadyExists means an attempt to create an entity failed because one
	// already exists.
	// Encore will not generate this error code.
	AlreadyExists ErrCode = 6

	// PermissionDenied indicates the caller does not have permission to
	// execute the specified operation. It must not be used for rejections
	// caused by exhausting some resource (use ResourceExhausted
	// instead for those errors). It must not be
	// used if the caller cannot be identified (use Unauthenticated
	// instead for those errors).
	// Encore will not generate this error code.
	PermissionDenied ErrCode = 7

	// ResourceExhausted indicates some resource has been exhausted, perhaps
	// a per-user quota, or perhaps the entire file system is out of space.
	// Encore will generate this error code in out-of-memory and server overload
	// situations, or when a message is larger than the configured maximum size.
	ResourceExhausted ErrCode = 8

	// FailedPrecondition indicates operation was rejected because the
	// system is not in a state required for the operation's execution.
	// For example, directory to be deleted may be non-empty, an rmdir
	// operation is applied to a non-directory, etc.
	// A litmus test that may help a service implementor in deciding
	// between FailedPrecondition, Aborted, and Unavailable:
	//  (a) Use Unavailable if the client can retry just the failing call.
	//  (b) Use Aborted if the client should retry at a higher-level
	//      (e.g., restarting a read-modify-write sequence).
	//  (c) Use FailedPrecondition if the client should not retry until
	//      the system state has been explicitly fixed. E.g., if an "rmdir"
	//      fails because the directory is non-empty, FailedPrecondition
	//      should be returned since the client should not retry unless
	//      they have first fixed up the directory by deleting files from it.
	//  (d) Use FailedPrecondition if the client performs conditional
	//      Get/Update/Delete on a resource and the resource on the
	//      server does not match the condition. E.g., conflicting
	//      read-modify-write on the same resource.
	// Encore will not generate this error code.
	FailedPrecondition ErrCode = 9

	// Aborted indicates the operation was aborted, typically due to a
	// concurrency issue like sequencer check failures, transaction aborts,
	// etc.
	// See litmus test above for deciding between FailedPrecondition,
	// Aborted, and Unavailable.
	Aborted ErrCode = 10

	// OutOfRange means operation was attempted past the valid range.
	// E.g., seeking or reading past end of file.
	// Unlike InvalidArgument, this error indicates a problem that may
	// be fixed if the system state changes. For example, a 32-bit file
	// system will generate InvalidArgument if asked to read at an
	// offset that is not in the range [0,2^32-1], but it will generate
	// OutOfRange if asked to read from an offset past the current
	// file size.
	// There is a fair bit of overlap between FailedPrecondition and
	// OutOfRange. We recommend using OutOfRange (the more specific
	// error) when it applies so that callers who are iterating through
	// a space can easily look for an OutOfRange error to detect when
	// they are done.
	// Encore will not generate this error code.
	OutOfRange ErrCode = 11

	// Unimplemented indicates operation is not implemented or not
	// supported/enabled in this service.
	// Encore will generate this error code when an endpoint does not exist.
	Unimplemented ErrCode = 12

	// Internal errors. Means some invariants expected by underlying
	// system has been broken. If you see one of these errors,
	// something is very broken.
	// Encore will generate this error code in several internal error conditions.
	Internal ErrCode = 13

	// Unavailable indicates the service is currently unavailable.
	// This is a most likely a transient condition and may be corrected
	// by retrying with a backoff. Note that it is not always safe to retry
	// non-idempotent operations.
	// See litmus test above for deciding between FailedPrecondition,
	// Aborted, and Unavailable.
	// Encore will generate this error code in aubrupt shutdown of a server process
	// or network connection.
	Unavailable ErrCode = 14

	// DataLoss indicates unrecoverable data loss or corruption.
	// Encore will not generate this error code.
	DataLoss ErrCode = 15

	// Unauthenticated indicates the request does not have valid
	// authentication credentials for the operation.
	// Encore will generate this error code when the authentication metadata
	// is invalid or missing, and expects auth handlers to return errors with
	// this code when the auth token is not valid.
	Unauthenticated ErrCode = 16

func Code

func Code(err error) (_ ErrCode)

Code reports the error code from an error. If err is nil it reports OK. Otherwise if err is not an *Error it reports Unknown.

func (ErrCode) HTTPStatus

func (c ErrCode) HTTPStatus() int

HTTPStatus reports a suitable HTTP status code for an error, based on its code. If err is nil it reports 200. If it's not an *Error it reports 500.

func (ErrCode) MarshalJSON

func (c ErrCode) MarshalJSON() ([]byte, error)

func (ErrCode) String

func (c ErrCode) String() string

String returns the string representation of c.

type ErrDetails

type ErrDetails interface {
	ErrDetails() // marker method; it need not do anything

ErrDetails is a marker interface for telling Encore the type is used for reporting error details.

We require a marker method (as opposed to using interface{}) to facilitate static analysis and to ensure the type can be properly serialized across the network.

func Details

func Details(err error) (_ ErrDetails)

Details reports the error details included in the error. If err is nil or the error lacks details it reports nil.

type Error

type Error struct {
	// Code is the error code to return.
	Code ErrCode `json:"code"`
	// Message is a descriptive message of the error.
	Message string `json:"message"`
	// Details are user-defined additional details.
	Details ErrDetails `json:"details"`
	// Meta are arbitrary key-value pairs for use within
	// the Encore application. They are not exposed to external clients.
	Meta Metadata `json:"-"`

An Error is an error that provides structured information about the error. It includes an error code, a message, optionally additional structured details about the error and arbitrary key-value metadata.

The Details field is returned to external clients. The Meta field is only exposed to internal calls within Encore.

Internally it captures an underlying error for printing and for use with errors.Is/As and call stack information.

To provide accurate stack information, users are expected to convert non-Error errors into *Error as close to the root cause as possible. This is made simple with Wrap.

func (*Error) Error

func (*Error) Error() (_ string)

Error reports the error code and message.

func (*Error) ErrorMessage

func (*Error) ErrorMessage() (_ string)

ErrorMessage reports the error message, joining this error's message with the messages from any underlying errors.

func (*Error) Unwrap

func (*Error) Unwrap() (_ error)

Unwrap returns the underlying error, if any.

type Metadata added in v0.13.1

type Metadata map[string]interface{}

Metadata represents structured key-value pairs, for attaching arbitrary metadata to errors. The metadata is propagated between internal services but is not exposed to external clients.

func Meta added in v0.13.1

func Meta(err error) (_ Metadata)

Meta reports the metadata included in the error. If err is nil or the error lacks metadata it reports nil.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL