Error Handling

Handle errors so callers keep context, reviewers can follow the failure path, and controllers stay alive.

Most error-handling issues in this repository are not about catching more failures. They are about returning failures with enough structure and context that the next layer can make the right decision without guessing. These rules keep that path predictable.

Decision matrix

Default error-handling rules

Default error-handling rules.

Rule	Expected default	Avoid
Wrap returned errors	Add local context and preserve the chain with %w.	Returning an upstream error with no explanation of what failed here.
Use guard clauses	Return early on failure and keep the happy path unindented.	Nesting success logic inside if err == nil branches.
Check Kubernetes error types explicitly	Handle NotFound and similar typed API failures with apierrors helpers.	String-matching Kubernetes errors.
Define checkable sentinels only for real control flow	Expose well-known errors when callers truly need errors.Is behavior.	Creating exported errors for every failure string in the codebase.
Do not panic in controllers	Return an error or surface an internal invariant failure explicitly.	Panics that can crash operator management for every cluster.

Wrapping and context

if err := r.Client.Create(ctx, secret); err != nil {
    return fmt.Errorf("create bootstrap secret %s/%s: %w", secret.Namespace, secret.Name, err)
}

Kubernetes typed errors

if err := r.Client.Get(ctx, key, secret); err != nil {
    if apierrors.IsNotFound(err) {
        return r.createSecret(ctx, ...)
    }

    return fmt.Errorf("get secret %s: %w", key.Name, err)
}

Checkable internal errors

Use exported sentinel errors only when the caller genuinely needs to branch on the result:

var (
    ErrClusterLocked = errors.New("cluster is locked")
    ErrNoLeader = errors.New("no leader available")
)

No panics in controller or internal logic paths

If a nil or impossible state appears, return a contextual error and let the caller decide how to surface it. A panic in a reconcile worker can take down management for the entire operator process.

Related coding rules

Go style guideReturn to naming, imports, and logging rules that sit next to error handling in normal implementation work.Security practicesOpen the secure-coding guidance when the error path also handles secrets, external input, or filesystem state.Testing strategyUse the testing guide when a failure path needs explicit unit, integration, or E2E coverage.