Golang Uber Dig

Persona: You are a Go architect wiring an application graph with dig. You keep the container at the composition root, depend on interfaces not concrete types, and treat constructor errors as first-class failures.

Using uber-go/dig for Dependency Injection in Go

Reflection-based DI toolkit, designed to power application frameworks (it is the engine behind uber-go/fx) and resolve object graphs during startup.

Official Resources:

• pkg.go.dev/go.uber.org/dig
• github.com/uber-go/dig

This skill is not exhaustive. Please refer to library documentation and code examples for more information. Context7 can help as a discoverability platform.

go get go.uber.org/dig

dig vs. fx

fx is built on dig and shares the same container engine — the DI primitives (Provide, Invoke, In/Out structs, named values, value groups) are identical. fx.In/fx.Out are re-exports of dig.In/dig.Out.

What fx adds on top of dig:

Choose dig when you need the wiring graph only: CLI tools, libraries exposing a container to callers, test harnesses, or embedding DI into an existing app that manages its own lifecycle.

Choose fx for long-running services (HTTP servers, workers, daemons) — lifecycle and signal handling are non-negotiable there. See samber/cc-skills-golang@golang-uber-fx skill.

Container

import "go.uber.org/dig"

c := dig.New()

Useful options: dig.DeferAcyclicVerification() (faster startup), dig.RecoverFromPanics() (turn panics into dig.PanicError), dig.DryRun(true) (validate without invoking).

Provide and Invoke

// Register a constructor — lazy, only runs when its output is needed
err := c.Provide(func(cfg *Config) (*sql.DB, error) {
    return sql.Open("postgres", cfg.DSN)
})

// Pull a service out of the container by asking for it as a function parameter
err = c.Invoke(func(db *sql.DB) error {
    return db.Ping()
})

Constructors are lazy and memoized: each output type is built once and shared (singleton per container). Provide errors at registration if the constructor is malformed; Invoke returns the constructor's error wrapped with the dependency path that triggered it.

A dig constructor is any function. Inputs are dependencies, outputs are provided types. error (last return) signals construction failure. Follow "accept interfaces, return structs".

Parameter Objects with dig.In

Once a constructor has 4+ dependencies, embed dig.In to group them as struct fields and tag fields:

type HandlerParams struct {
    dig.In

    Logger *zap.Logger
    DB     *sql.DB
    Cache  *redis.Client `optional:"true"`           // zero value if not provided
    DBRO   *sql.DB       `name:"readonly"`           // named dependency
    Routes []http.Handler `group:"routes"`           // value group
}

func NewHandler(p HandlerParams) *Handler { /* ... */ }

Tags: name:"...", optional:"true", group:"...".

Result Objects with dig.Out

Return several values from one constructor and attach name/group tags to results:

type ConnResult struct {
    dig.Out

    ReadWrite *sql.DB `name:"primary"`
    ReadOnly  *sql.DB `name:"readonly"`
}

func NewConnections(cfg *Config) (ConnResult, error) { /* ... */ }

Named Values

Two providers of the same type collide. Disambiguate with dig.Name:

c.Provide(NewPrimaryDB,  dig.Name("primary"))
c.Provide(NewReadOnlyDB, dig.Name("readonly"))

Consume by adding name:"primary" / name:"readonly" to a dig.In field.

Value Groups

Many providers, one consumer slice — typical for HTTP handlers, health checks, migrations:

type RouteResult struct {
    dig.Out
    Handler http.Handler `group:"routes"`
}

func NewUserHandler(db *sql.DB) RouteResult { /* ... */ }
func NewPostHandler(db *sql.DB) RouteResult { /* ... */ }

type ServerParams struct {
    dig.In
    Routes []http.Handler `group:"routes"`
}

Flatten — append ,flatten (e.g. group:"routes,flatten") to unwrap a slice instead of nesting it. Group order is not guaranteed; if order matters, provide an explicit ordered slice from a single constructor.

Provide as Interface (dig.As)

Register a concrete constructor and expose it under one or more interfaces without a separate adapter:

c.Provide(NewPostgresDB, dig.As(new(Database), new(io.Closer)))
// Consumers ask for Database or io.Closer; *PostgresDB stays hidden.

Full Application Example

func main() {
    c := dig.New()

    must(c.Provide(NewConfig))
    must(c.Provide(NewLogger))
    must(c.Provide(NewDatabase))
    must(c.Provide(NewServer))

    err := c.Invoke(func(srv *http.Server) error {
        return srv.ListenAndServe()
    })
    if err != nil {
        log.Fatal(err)
    }
}

func must(err error) { if err != nil { panic(err) } }

dig has no built-in lifecycle. If you need OnStart/OnStop hooks, signal handling, and graceful shutdown, use fx — see samber/cc-skills-golang@golang-uber-fx skill.

For Decorate, Scopes, optional deps, error helpers, and Visualize, see advanced.md.

Best Practices

1. Keep the container at the composition root — never pass *dig.Container as a parameter; treat it like a plumbing detail of main(). Service-locator patterns defeat the testability gains of DI. 2. Depend on interfaces, not concrete types — lets you swap implementations in tests without touching production code, and lets you use dig.As to expose narrow interfaces from wide structs. 3. Prefer parameter objects (dig.In structs) once a constructor has 4+ dependencies — call sites stay readable and adding a new dependency is a one-line change instead of a signature break. 4. Group registration by module (one file per module that calls c.Provide for its types) — review and refactoring become a per-module concern, and you can extract a module into a fx.Module later without rewriting wiring. 5. Validate the graph eagerly in tests — call c.Invoke against the composition root in CI to surface missing providers at boot time, not at first request. DryRun(true) skips constructor execution. 6. Return errors from constructors instead of panicking — dig wraps them with the dependency path, which makes the failure point obvious.

Common Mistakes

Testing

dig containers are cheap — build a fresh one per test, override providers with Decorate, and call Invoke to drive the system. For full patterns (per-test wiring, shared helpers, graph validation in CI, asserting wire-time errors, recovering from constructor panics), see testing.md.

Further Reading

• advanced.md — Decorate, Scopes, optional deps, error helpers, Visualize, full Quick Reference
• recipes.md — end-to-end examples: HTTP server with route group, two databases, request scopes, decorators, dry-run validation
• testing.md — testing patterns and graph validation

Cross-References

• → See samber/cc-skills-golang@golang-uber-fx skill for application lifecycle, modules, and signal-aware Run() built on top of dig
• → See samber/cc-skills-golang@golang-dependency-injection skill for DI concepts and library comparison
• → See samber/cc-skills-golang@golang-samber-do skill for a generics-based alternative without reflection
• → See samber/cc-skills-golang@golang-google-wire skill for compile-time DI (no runtime container)
• → See samber/cc-skills-golang@golang-structs-interfaces skill for interface design patterns
• → See samber/cc-skills-golang@golang-testing skill for general testing patterns

If you encounter a bug or unexpected behavior in uber-go/dig, open an issue at <https://github.com/uber-go/dig/issues>.

Advanced — uber-go/dig

Detail topics that are referenced from SKILL.md. Each section is self-contained.

Decorate

Decorate modifies a value already provided in the container — the decorator receives the original instance and returns a replacement. Common uses: enriching a logger with context, wrapping a metrics scope with tags, swapping a real client for a recording one in a child scope.

c.Decorate(func(log *zap.Logger) *zap.Logger {
    return log.Named("worker")
})

Decorators apply to the scope they were registered in and to that scope's descendants. Use them at scope boundaries or package wiring boundaries, not in main(), so changes stay local.

Scopes

A Scope is a child container that inherits providers from its parent and can add or override its own. Scopes let request-, tenant-, or module-level dependencies coexist with shared singletons:

root := dig.New()
root.Provide(NewLogger)
root.Provide(NewDatabase)

requestScope := root.Scope("request")
requestScope.Provide(NewRequestContext)            // only visible inside requestScope
requestScope.Decorate(func(l *zap.Logger) *zap.Logger {
    return l.With(zap.String("scope", "request"))
})

By default, providers registered to a scope are private to that scope and its children. Pass dig.Export(true) to Provide inside a scope to make the type visible from the parent:

requestScope.Provide(NewSharedCache, dig.Export(true))

Optional Dependencies

optional:"true" lets a consumer compile and run when a provider is missing. Use it sparingly — optional dependencies hide configuration mistakes. They make sense for genuinely optional features (a tracing exporter, an in-memory cache) but not for core services like a database.

type Params struct {
    dig.In

    Logger *zap.Logger
    Tracer trace.Tracer `optional:"true"`
}

Error Handling

dig wraps the constructor error with the dependency path so you can see _which_ graph edge failed:

if err := c.Invoke(run); err != nil {
    // err describes the chain: "could not build *http.Server: ..."
}

Useful helpers:

• errors.As(err, &dig.Error{}) — true if the error originated inside dig
• dig.RootCause(err) — unwrap to the original constructor error returned by user code
• dig.IsCycleDetected(err) — true if the graph contains a cycle (typically reported at first Invoke unless DeferAcyclicVerification is set)
• errors.As(err, &dig.PanicError{}) — when RecoverFromPanics is enabled, a panicking constructor surfaces as this typed error

Visualization

dig can emit the dependency graph in DOT format — useful when wiring becomes too tangled to reason about by reading code:

f, _ := os.Create("graph.dot")
_ = dig.Visualize(c, f)
// then: dot -Tpng graph.dot -o graph.png

dig.VisualizeError(err) highlights the failed edges when an Invoke returns an error — invaluable for debugging "missing type" failures in deep graphs.

Quick Reference

Container

Provide options

Container options

Errors

Recipes — uber-go/dig

End-to-end examples that go beyond the SKILL.md basics. Each recipe is self-contained and shows a real wiring problem.

HTTP server with route group

package main

import (
    "fmt"
    "log"
    "net/http"

    "go.uber.org/dig"
)

// Each handler contributes one route to the "routes" group.
type RouteResult struct {
    dig.Out
    Route Route `group:"routes"`
}

type Route struct {
    Pattern string
    Handler http.Handler
}

func NewHealthRoute() RouteResult {
    return RouteResult{Route: Route{
        Pattern: "/health",
        Handler: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
            w.WriteHeader(http.StatusOK)
        }),
    }}
}

func NewUserRoute(repo *UserRepo) RouteResult {
    return RouteResult{Route: Route{
        Pattern: "/users",
        Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            users, err := repo.List(r.Context())
            if err != nil {
                http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
                return
            }
            fmt.Fprintf(w, "%d users", len(users))
        }),
    }}
}

// The server consumes every Route registered to "routes".
type ServerParams struct {
    dig.In
    Routes []Route `group:"routes"`
}

func NewServer(p ServerParams) *http.Server {
    mux := http.NewServeMux()
    for _, r := range p.Routes {
        mux.Handle(r.Pattern, r.Handler)
    }
    return &http.Server{Addr: ":8080", Handler: mux}
}

func main() {
    c := dig.New()

    must(c.Provide(NewDB))           // *sql.DB
    must(c.Provide(NewUserRepo))     // *UserRepo
    must(c.Provide(NewHealthRoute))  // adds to group
    must(c.Provide(NewUserRoute))    // adds to group
    must(c.Provide(NewServer))

    err := c.Invoke(func(srv *http.Server) error {
        log.Println("listening on", srv.Addr)
        return srv.ListenAndServe()
    })
    if err != nil {
        log.Fatal(err)
    }
}

func must(err error) {
    if err != nil {
        panic(err)
    }
}

Two databases (read-write + read-only)

type DBResult struct {
    dig.Out
    Primary  *sql.DB `name:"primary"`
    ReadOnly *sql.DB `name:"readonly"`
}

func NewDatabases(cfg *Config) (DBResult, error) {
    rw, err := sql.Open("postgres", cfg.PrimaryDSN)
    if err != nil {
        return DBResult{}, fmt.Errorf("primary: %w", err)
    }
    ro, err := sql.Open("postgres", cfg.ReadOnlyDSN)
    if err != nil {
        rw.Close()
        return DBResult{}, fmt.Errorf("readonly: %w", err)
    }
    return DBResult{Primary: rw, ReadOnly: ro}, nil
}

type RepoParams struct {
    dig.In
    Writer *sql.DB `name:"primary"`
    Reader *sql.DB `name:"readonly"`
}

func NewUserRepo(p RepoParams) *UserRepo {
    return &UserRepo{w: p.Writer, r: p.Reader}
}

Provide as interface (dig.As) to hide concrete types

type Cache interface {
    Get(key string) (string, bool)
    Set(key, value string)
}

type RedisCache struct {
    client *redis.Client
    metrics *Metrics // an internal field consumers should not see
}

func NewRedisCache(client *redis.Client, m *Metrics) *RedisCache {
    return &RedisCache{client: client, metrics: m}
}

func (c *RedisCache) Get(key string) (string, bool) { /* ... */ }
func (c *RedisCache) Set(key, value string)         { /* ... */ }

func main() {
    c := dig.New()
    must(c.Provide(NewRedisClient))
    must(c.Provide(NewMetrics))
    // Consumers see Cache, never *RedisCache or its internals.
    must(c.Provide(NewRedisCache, dig.As(new(Cache))))
    must(c.Invoke(func(cache Cache) {
        cache.Set("hello", "world")
    }))
}

Request-scoped dependencies

A child scope inherits its parent's providers but adds request-local ones:

root := dig.New()
must(root.Provide(NewLogger))
must(root.Provide(NewDB))
must(root.Provide(NewHandler)) // *Handler is shared; the scope inherits it

func handle(w http.ResponseWriter, req *http.Request) {
    scope := root.Scope("request")

    // Request-scoped values
    must(scope.Provide(func() *http.Request { return req }))
    must(scope.Provide(func() RequestID { return RequestID(req.Header.Get("X-Request-ID")) }))
    must(scope.Decorate(func(l *zap.Logger) *zap.Logger {
        return l.With(zap.String("request_id", req.Header.Get("X-Request-ID")))
    }))

    err := scope.Invoke(func(h *Handler) error {
        return h.Serve(w, req)
    })
    if err != nil {
        http.Error(w, err.Error(), 500)
    }
}

The decorator only applies inside the request scope — sibling scopes (other in-flight requests) keep their own logger.

Optional dependency for graceful degradation

type WorkerParams struct {
    dig.In

    DB     *sql.DB
    Tracer trace.Tracer `optional:"true"` // app still boots without OTel
}

func NewWorker(p WorkerParams) *Worker {
    w := &Worker{db: p.DB}
    if p.Tracer != nil {
        w.tracer = p.Tracer
    } else {
        w.tracer = trace.NewNoopTracerProvider().Tracer("noop")
    }
    return w
}

Reach for optional only when the dependency is genuinely optional — a missing DB hidden behind optional becomes a nil-pointer panic at first use.

Decorate to add cross-cutting behavior

// Wrap the *sql.DB with a metrics-recording wrapper everywhere.
must(c.Decorate(func(db *sql.DB, m *Metrics) *sql.DB {
    return wrapWithMetrics(db, m)
}))

// Wrap the logger with service tags.
must(c.Decorate(func(log *zap.Logger, cfg *Config) *zap.Logger {
    return log.With(
        zap.String("service", cfg.ServiceName),
        zap.String("env", cfg.Env),
    )
}))

Decorators are scope-local. A decorator on the root applies everywhere; a decorator on a child scope only applies to that subtree.

DryRun for graph validation in tests

func TestWiringIsValid(t *testing.T) {
    c := dig.New(dig.DryRun(true))

    // Register everything main() registers
    must := func(err error) {
        require.NoError(t, err)
    }
    must(c.Provide(NewConfig))
    must(c.Provide(NewLogger))
    must(c.Provide(NewDB))
    must(c.Provide(NewServer))

    // Invoke the composition root: dig validates types without running constructors.
    require.NoError(t, c.Invoke(func(*http.Server) {}))
}

This catches "no provider for \*X" failures at build time instead of in production.

Visualizing a failed graph

err := c.Invoke(run)
if err != nil {
    f, _ := os.Create("graph.dot")
    defer f.Close()
    _ = dig.Visualize(c, f, dig.VisualizeError(err))
    log.Fatalf("wiring failed (graph in graph.dot): %v", err)
}
// Render: dot -Tpng graph.dot -o graph.png

VisualizeError highlights the missing edges in red — much faster than reading the wrapped error chain.

Testing with uber-go/dig

dig containers are cheap to create. Build a fresh one per test, override what you need, drive the system with Invoke.

Per-test container

func TestUserService_Create(t *testing.T) {
    c := dig.New()

    fakeDB := &fakeDatabase{}
    require.NoError(t, c.Provide(func() Database { return fakeDB }))
    require.NoError(t, c.Provide(NewUserService))

    require.NoError(t, c.Invoke(func(s *UserService) {
        err := s.Create(context.Background(), "alice@example.com")
        require.NoError(t, err)
    }))

    require.Len(t, fakeDB.inserted, 1)
}

Shared test wiring

For larger suites, factor the common providers into a helper:

func newTestContainer(t *testing.T, overrides ...func(*dig.Container)) *dig.Container {
    t.Helper()
    c := dig.New()
    require.NoError(t, c.Provide(NewTestLogger))
    require.NoError(t, c.Provide(NewInMemoryCache))
    require.NoError(t, c.Provide(func() Database { return &fakeDatabase{} }))
    require.NoError(t, c.Provide(NewUserService))

    for _, override := range overrides {
        override(c)
    }
    return c
}

func TestUserService_NotFound(t *testing.T) {
    c := newTestContainer(t, func(c *dig.Container) {
        // Replace the default DB with one that returns sql.ErrNoRows.
        require.NoError(t, c.Decorate(func(db Database) Database {
            return &notFoundDB{Database: db}
        }))
    })

    require.NoError(t, c.Invoke(func(s *UserService) {
        _, err := s.Get(context.Background(), "missing")
        require.ErrorIs(t, err, ErrUserNotFound)
    }))
}

Decorate is the cleanest way to swap a dependency in tests — the test reads almost like production wiring with one extra line.

Validate the production graph in CI

func TestProductionGraph(t *testing.T) {
    c := dig.New(dig.DryRun(true))

    // Replicate every Provide() from main()
    require.NoError(t, registerAll(c))

    // Invoke the same root the production binary does
    require.NoError(t, c.Invoke(func(*http.Server, *Worker, *MetricsExporter) {}))
}

DryRun(true) skips constructor execution — the graph is validated structurally. This catches missing-provider and type-mismatch errors without spinning up real DB connections.

Detecting cycles before deploy

A cyclic graph fails at the first Invoke (or at Provide time when DeferAcyclicVerification is off, which is the default):

func TestNoCycles(t *testing.T) {
    c := dig.New()
    require.NoError(t, registerAll(c))

    err := c.Invoke(func(*App) {})
    require.False(t, dig.IsCycleDetected(err), "cycle in dependency graph: %v", err)
}

Asserting a constructor's error path

When a constructor returns an error, dig wraps it with the dependency path. Use dig.RootCause to assert the original error:

func TestDBProvider_BadDSN(t *testing.T) {
    c := dig.New()
    require.NoError(t, c.Provide(func() *Config {
        return &Config{DSN: "not a dsn"}
    }))
    require.NoError(t, c.Provide(NewDB))

    err := c.Invoke(func(*sql.DB) {})
    require.Error(t, err)
    require.ErrorContains(t, dig.RootCause(err), "invalid connection string")
}

Recovering from constructor panics

Wrap constructors that may panic on misuse so the test reports a typed error instead of crashing the runner:

c := dig.New(dig.RecoverFromPanics())

require.NoError(t, c.Provide(func() *App {
    panic("intentionally broken")
}))

err := c.Invoke(func(*App) {})

var pe dig.PanicError
require.True(t, errors.As(err, &pe))
require.Contains(t, pe.Error(), "intentionally broken")