github.com/pkg/errors v0.9.1: Cause

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify github.com/pkg/errors.Cause in pkg:golang/github.com/pkg/errors@v0.9.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/pkg/errors@v0.9.1
Demonstrate these symbols/APIs:
  - github.com/pkg/errors.Cause

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:c95e29fb3811e6d1ee64d95255f3f13b89c95f636f671daf79501c1d376d7f12","contract":["errors.Cause returns nil when passed a nil error","errors.Cause returns the original unnested error when passed an error without a cause","errors.Cause unwraps single-layer errors annotated with errors.Wrap, errors.WithMessage, or errors.WithStack to the root error","errors.Cause recursively traverses nested error chains combining errors.Wrap, errors.WithMessage, and errors.WithStack to find the root cause","errors.Cause supports custom error types implementing the causer interface with a Cause() error method"],"goal":"verify github.com/pkg/errors.Cause in pkg:golang/github.com/pkg/errors@v0.9.1","kind":"HOW","packages":["pkg:golang/github.com/pkg/errors@v0.9.1"],"schemaVersion":1,"symbols":["github.com/pkg/errors.Cause"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/pkg/errors@v0.9.1"],"schemaVersion":1,"subject":"pkg:golang/github.com/pkg/errors@v0.9.1","symbols":["github.com/pkg/errors.Cause"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

require github.com/pkg/errors v0.9.1

github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=

package main

import (
	"fmt"
	"io"

	"github.com/pkg/errors"
)

// performTask simulates an operation that encounters an EOF error and wraps it.
func performTask() error {
	return errors.Wrap(io.EOF, "failed to read stream")
}

// executeWorkflow wraps the error from performTask with additional high-level context.
func executeWorkflow() error {
	err := performTask()
	if err != nil {
		return errors.WithMessage(err, "workflow execution failed")
	}
	return nil
}

func main() {
	err := executeWorkflow()
	if err != nil {
		fmt.Printf("Encountered error: %v\n", err)
		root := errors.Cause(err)
		fmt.Printf("Unwrapped root cause: %v\n", root)
		if root == io.EOF {
			fmt.Println("Successfully identified root cause as io.EOF via errors.Cause")
		}
	}
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/pkg/errors.Cause in pkg:golang/github.com/pkg/errors@v0.9.1",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/pkg/errors@v0.9.1"
  ],
  "symbols": [
    "github.com/pkg/errors.Cause"
  ]
}

package main

import (
	"fmt"
	"os"

	"github.com/pkg/errors"
)

type customCauser struct {
	msg   string
	inner error
}

func (c *customCauser) Error() string {
	return c.msg
}

func (c *customCauser) Cause() error {
	return c.inner
}

func main() {
	if err := runContract(); err != nil {
		fmt.Fprintf(os.Stderr, "Contract verification failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("All github.com/pkg/errors.Cause contract assertions passed successfully.")
}

func runContract() error {
	// 1. errors.Cause returns nil when passed a nil error
	if cause := errors.Cause(nil); cause != nil {
		return fmt.Errorf("expected errors.Cause(nil) to be nil, got: %v", cause)
	}

	// 2. errors.Cause returns the original unnested error when passed an error without a cause
	plainErr := fmt.Errorf("standard unnested error")
	if cause := errors.Cause(plainErr); cause != plainErr {
		return fmt.Errorf("expected Cause(plainErr) == plainErr, got: %v", cause)
	}

	baseErr := errors.New("base errors.New error")
	if cause := errors.Cause(baseErr); cause != baseErr {
		return fmt.Errorf("expected Cause(baseErr) == baseErr, got: %v", cause)
	}

	// 3. errors.Cause unwraps single-layer errors annotated with errors.Wrap, errors.WithMessage, or errors.WithStack to the root error
	rootErr := errors.New("root failure")

	wrapped := errors.Wrap(rootErr, "context wrap")
	if cause := errors.Cause(wrapped); cause != rootErr {
		return fmt.Errorf("expected Cause(Wrap) == rootErr, got: %v", cause)
	}

	wrappedf := errors.Wrapf(rootErr, "context wrapf formatted %d", 101)
	if cause := errors.Cause(wrappedf); cause != rootErr {
		return fmt.Errorf("expected Cause(Wrapf) == rootErr, got: %v", cause)
	}

	withMsg := errors.WithMessage(rootErr, "context message")
	if cause := errors.Cause(withMsg); cause != rootErr {
		return fmt.Errorf("expected Cause(WithMessage) == rootErr, got: %v", cause)
	}

	withMsgf := errors.WithMessagef(rootErr, "context messagef formatted %s", "detail")
	if cause := errors.Cause(withMsgf); cause != rootErr {
		return fmt.Errorf("expected Cause(WithMessagef) == rootErr, got: %v", cause)
	}

	withStack := errors.WithStack(rootErr)
	if cause := errors.Cause(withStack); cause != rootErr {
		return fmt.Errorf("expected Cause(WithStack) == rootErr, got: %v", cause)
	}

	// 4. errors.Cause recursively traverses nested error chains combining errors.Wrap, errors.WithMessage, and errors.WithStack to find the root cause
	deepRoot := fmt.Errorf("deep root cause")
	layer1 := errors.Wrap(deepRoot, "layer 1 wrap")
	layer2 := errors.WithStack(layer1)
	layer3 := errors.WithMessage(layer2, "layer 3 with message")
	layer4 := errors.Wrapf(layer3, "layer 4 wrapf status %d", 500)
	layer5 := errors.WithMessagef(layer4, "layer 5 with messagef step %s", "pipeline")

	if cause := errors.Cause(layer5); cause != deepRoot {
		return fmt.Errorf("expected recursive unwrapping to yield deepRoot, got: %v", cause)
	}

	// 5. errors.Cause supports custom error types implementing the causer interface with a Cause() error method
	customRoot := errors.New("underlying cause in custom causer")
	causerErr := &customCauser{msg: "custom outer wrapper", inner: customRoot}
	nestedCustom := errors.Wrap(causerErr, "outermost wrap")

	if cause := errors.Cause(nestedCustom); cause != customRoot {
		return fmt.Errorf("expected Cause on nested custom causer to return customRoot, got: %v", cause)
	}

	return nil
}