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

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.WithMessage 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.WithMessage

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:df690a1c0c9039fa58fe65ce5ac4c699ad4695af41b150787d74942e51eaccac","contract":["WithMessage returns nil when err is nil","WithMessage prepends message to underlying error with colon and space separator","WithMessage preserves underlying root error retrievable via errors.Cause","WithMessage supports Go 1.13 error unwrapping via errors.Unwrap","WithMessage allows chaining multiple message annotations while preserving root cause","WithMessage formats with empty message as colon and space prefix before underlying error"],"goal":"verify github.com/pkg/errors.WithMessage 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.WithMessage"]},"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.WithMessage"],"verifierAdapter":"golang@1"}

module example.com/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"
)

// readResource simulates reading a resource that fails with an EOF.
func readResource() error {
	return io.EOF
}

// loadConfig simulates loading configuration and annotating lower-level errors.
func loadConfig() error {
	if err := readResource(); err != nil {
		return errors.WithMessage(err, "failed to read configuration file")
	}
	return nil
}

func main() {
	// Demonstrating WithMessage with nil error
	if err := errors.WithMessage(nil, "no error"); err != nil {
		panic("expected nil error")
	}

	// Demonstrating WithMessage annotating an error
	err := loadConfig()
	if err != nil {
		fmt.Println("Formatted error:", err.Error())
		fmt.Println("Underlying cause:", errors.Cause(err))
	}
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/pkg/errors.WithMessage 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.WithMessage"
  ]
}

package main

import (
	stderrors "errors"
	"fmt"
	"os"

	pkgerrors "github.com/pkg/errors"
)

func main() {
	// 1. WithMessage returns nil when err is nil
	if err := pkgerrors.WithMessage(nil, "context on nil"); err != nil {
		fmt.Fprintf(os.Stderr, "assertion 1 failed: expected nil, got %v\n", err)
		os.Exit(1)
	}

	rootErr := stderrors.New("disk full")

	// 2. WithMessage prepends message to underlying error with colon and space separator
	annotated := pkgerrors.WithMessage(rootErr, "write failed")
	expectedMsg := "write failed: disk full"
	if annotated.Error() != expectedMsg {
		fmt.Fprintf(os.Stderr, "assertion 2 failed: expected %q, got %q\n", expectedMsg, annotated.Error())
		os.Exit(1)
	}

	// 3. WithMessage preserves underlying root error retrievable via errors.Cause
	if cause := pkgerrors.Cause(annotated); cause != rootErr {
		fmt.Fprintf(os.Stderr, "assertion 3 failed: expected root error %v, got %v\n", rootErr, cause)
		os.Exit(1)
	}

	// 4. WithMessage supports Go 1.13 error unwrapping via errors.Unwrap
	if unwrapped := stderrors.Unwrap(annotated); unwrapped != rootErr {
		fmt.Fprintf(os.Stderr, "assertion 4 failed (Unwrap): expected %v, got %v\n", rootErr, unwrapped)
		os.Exit(1)
	}
	if !stderrors.Is(annotated, rootErr) {
		fmt.Fprintf(os.Stderr, "assertion 4 failed (Is): expected true\n")
		os.Exit(1)
	}

	// 5. WithMessage allows chaining multiple message annotations while preserving root cause
	chained := pkgerrors.WithMessage(annotated, "request processing failed")
	expectedChainedMsg := "request processing failed: write failed: disk full"
	if chained.Error() != expectedChainedMsg {
		fmt.Fprintf(os.Stderr, "assertion 5 failed: expected %q, got %q\n", expectedChainedMsg, chained.Error())
		os.Exit(1)
	}
	if cause := pkgerrors.Cause(chained); cause != rootErr {
		fmt.Fprintf(os.Stderr, "assertion 5 failed: expected cause %v, got %v\n", rootErr, cause)
		os.Exit(1)
	}

	// 6. WithMessage formats with empty message as colon and space prefix before underlying error
	emptyAnnotated := pkgerrors.WithMessage(rootErr, "")
	expectedEmptyMsg := ": disk full"
	if emptyAnnotated.Error() != expectedEmptyMsg {
		fmt.Fprintf(os.Stderr, "assertion 6 failed: expected %q, got %q\n", expectedEmptyMsg, emptyAnnotated.Error())
		os.Exit(1)
	}

	fmt.Println("All contract assertions passed.")
}