Errors and Failure Design

Close returns an error and a deferred call discards it. On a file you wrote to, that error can be the only report that your data never reached the disk, so a failed write ends up looking like a success.

error is a predeclared interface with exactly one method, Error() string. Any type that declares that method - a struct, a named int, anything - is an error and can be returned wherever error is expected.

Logging and returning reports one failure twice: the function writes a log record, then whoever called it reports the same failure again. Choose one role per error - either handle it and log it, or return it and stay silent.

Go reports failure as an ordinary value returned last, beside the real result. The caller tests err != nil before touching the other result, because on failure that result is only a zero value, not data.

An error string is rarely printed alone. Callers wrap it, so it lands in the middle of a longer message. Lowercase text with no trailing period or newline concatenates cleanly into one readable line.

A sentinel error is one package-level error value, such as var ErrNotFound = errors.New("not found"), that a package returns for a specific condition. Callers detect that condition by matching a returned error against that exported value.

Declare a struct holding the data and give it an Error() string method, normally on a pointer receiver. Any type with that method is usable as an error, and callers read the exported fields off the concrete value.

Export a sentinel value when the caller only needs a yes-or-no branch, and an error type when the caller needs data to act on. A sentinel commits the package to one identity; a type commits every exported field forever.

Put the classification in the error itself: an exported sentinel matched with errors.Is, or an error type with a method such as Retryable() bool found with errors.As. Both survive wrapping; a second bool return and message text do not.

The == operator only tests the outermost error value. If any layer in between returned a new error carrying the original as its cause, == stops matching. errors.Is walks that chain of causes and matches any error in it.

An Is method lets errors.Is treat your error as equivalent to a target it does not equal by value. While searching, errors.Is calls your Is method at your link and accepts a true answer as a match.

errors.Join skips every nil argument and returns a plain nil if all of them are nil. Otherwise it returns one error whose message is the non-nil errors' messages joined by newlines, one per line, with no trailing newline.

%w stores the original error inside the new one, giving the result an Unwrap method so errors.Is and errors.As can still find the cause. %v only copies the error's text, so that link is gone.

Both call Unwrap repeatedly. errors.Is compares each error in the chain to the target with ==; errors.As tries to assign each one into the pointer target's type and returns true at the first that fits.

Stop rendering err.Error() to callers. At one boundary helper, log the whole wrapped chain with a correlation id and write a fixed message plus that id. Caller-facing wording must be carried explicitly, never inherited.

Give the function a named error result and defer a closure that calls recover. When recover returns non-nil, the closure assigns a wrapped error to that named result, so the caller sees an ordinary error instead of a panic.

Panic only for bugs the program cannot continue past: impossible internal states, broken invariants, or setup at package init. Anything a caller could reasonably hit at runtime, including bad input, missing files and I/O failure, returns an error.

Go's built-in map is not safe for concurrent writes. The runtime notices the overlapping write and aborts the whole process with 'fatal error: concurrent map writes'. It is not a panic and the program does not continue past it.

recover() stops a panicking goroutine from dying and returns the value that was passed to panic. It works only when called directly inside a function that was deferred; called anywhere else it returns nil.

Inside the goroutine's own function, at the top, not in the code that started it. A recovery only takes effect in a function deferred by the goroutine that panicked, and a panic that escapes any goroutine terminates the whole process.

ctx.Err() returns nil while the context is still live, context.Canceled once a cancel function has been called, and context.DeadlineExceeded once the context's deadline has passed. Match them with errors.Is, not with ==.

io.EOF is a sentinel error the io.Reader contract uses to say the stream is finished, so nothing went wrong. Callers detect it, stop reading and return success; they never log it or pass it on as a fault.

Use errors.Is(err, fs.ErrNotExist). os.Open returns a *fs.PathError wrapping the operating system's error, so comparing the returned error directly against fs.ErrNotExist is always false; errors.Is unwraps the chain and finds the sentinel.

The io.Reader contract lets a reader that hits the end of its data while filling your buffer report both at once. Process the n bytes returned before you inspect the error, or the last chunk of the stream is silently dropped.

They are two unrelated sentinel values. A read that fails because an I/O deadline expired wraps os.ErrDeadlineExceeded; only a finished context.Context yields context.DeadlineExceeded. Both report Timeout() true through the net.Error interface.