caddyserver/caddy · warning

tracerProvider shutdown: %w

Error message

tracerProvider shutdown: %w

What it means

Returned by the tracing module's Cleanup (implements caddy.CleanerUpper) when shutting down the OpenTelemetry tracer provider fails during config unload or process exit. The %w wrapping preserves the underlying otel error for errors.Is/As inspection.

Source

Thrown at modules/caddyhttp/tracing/module.go:61

		New: func() caddy.Module { return new(Tracing) },
	}
}

// Provision implements caddy.Provisioner.
func (ot *Tracing) Provision(ctx caddy.Context) error {
	ot.logger = ctx.Logger()

	var err error
	ot.otel, err = newOpenTelemetryWrapper(ctx, ot.SpanName, ot.SpanAttributes)

	return err
}

// Cleanup implements caddy.CleanerUpper and closes any idle connections. It
// calls Shutdown method for a trace provider https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#shutdown.
func (ot *Tracing) Cleanup() error {
	if err := ot.otel.cleanup(ot.logger); err != nil {
		return fmt.Errorf("tracerProvider shutdown: %w", err)
	}
	return nil
}

// ServeHTTP implements caddyhttp.MiddlewareHandler.
func (ot *Tracing) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error {
	return ot.otel.ServeHTTP(w, r, next)
}

// UnmarshalCaddyfile sets up the module from Caddyfile tokens. Syntax:
//
//	tracing {
//	    [span <span_name>]
//		[span_attributes {
//			attr1 value1
//			attr2 value2
//		}]
//	}

View on GitHub (pinned to 50e54ee279)

Solutions

1. Check the wrapped error text: 'context canceled' during rapid reloads is usually benign; connection refused means the endpoint is down
2. Ensure the OTLP endpoint (OTEL_EXPORTER_OTLP_ENDPOINT) is reachable and correct
3. Upgrade/align opentelemetry Go library versions in custom builds (go mod tidy)
4. For noisy shutdowns on reload, stabilize the tracing endpoint or accept the non-fatal cleanup error

Example fix

# before
export OTEL_EXPORTER_OTLP_ENDPOINT=http://tracing-down:4318  # host down on reload

# after
export OTEL_EXPORTER_OTLP_ENDPOINT=http://tracing.internal:4318  # reachable endpoint

When it happens

Trigger: Any config change/reload or shutdown where otel.shutdown() fails: e.g. the exporter's Shutdown returning an error because the remote OTLP endpoint connection is broken, or shutdown was already called (context canceled).

Common situations: Reloading Caddy while the tracing backend (Jaeger/Collector/Zipkin) is unreachable, exporters buffering spans that cannot flush on shutdown, or mismatched otel library versions in custom builds.

Related errors

• creating resource error: %w
• tracerProvider shutdown error: %w
• %v; additionally, aborting app %s: %v
• server graceful shutdown %ds timeout
• creating OTLP metric reader: %w

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/51b8ad093a81a022. Report an issue: GitHub.