{"record":{"id":"437ebdb84f53ef31","repo":"caddyserver/caddy","slug":"tracerprovider-shutdown-error-w","errorCode":null,"errorMessage":"tracerProvider shutdown error: %w","messagePattern":"tracerProvider shutdown error: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"modules/caddyhttp/tracing/tracerprovider.go","lineNumber":68,"sourceCode":"\tt.mu.Lock()\n\tdefer t.mu.Unlock()\n\n\tif t.tracerProvidersCounter > 0 {\n\t\tt.tracerProvidersCounter--\n\t}\n\n\tif t.tracerProvidersCounter == 0 {\n\t\tif t.tracerProvider != nil {\n\t\t\t// tracerProvider.ForceFlush SHOULD be invoked according to https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#forceflush\n\t\t\tif err := t.tracerProvider.ForceFlush(context.Background()); err != nil {\n\t\t\t\tif c := logger.Check(zapcore.ErrorLevel, \"forcing flush\"); c != nil {\n\t\t\t\t\tc.Write(zap.Error(err))\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// tracerProvider.Shutdown MUST be invoked according to https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#shutdown\n\t\t\tif err := t.tracerProvider.Shutdown(context.Background()); err != nil {\n\t\t\t\treturn fmt.Errorf(\"tracerProvider shutdown error: %w\", err)\n\t\t\t}\n\t\t}\n\n\t\tt.tracerProvider = nil\n\t}\n\n\treturn nil\n}\n","sourceCodeStart":50,"sourceCodeEnd":77,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddyhttp/tracing/tracerprovider.go#L50-L77","documentation":"Returned by the tracing module's global tracer-provider cleanup when the last tracing handler is being torn down and tracerProvider.Shutdown(context.Background()) fails. Shutdown flushes any buffered spans to the exporter, so an unreachable or already-closed OTLP endpoint, or an exporter already shut down by a concurrent reload, produces this error. It surfaces during Caddy config unload/reload or process exit, not during request serving.","triggerScenarios":"Config reload or shutdown of the last route using `tracing` while the OTLP collector is down, has closed the connection, or the endpoint URL is wrong — the BatchSpanProcessor's final flush fails inside Shutdown. Also occurs when OTEL_EXPORTER_OTLP_TIMEOUT is too small for a slow collector, or when two reloads race and one shutdown closes the exporter first.","commonSituations":"Collector container restarting while Caddy reloads config; collector behind a load balancer that drops idle connections; aggressive OTEL_EXPORTER_OTLP_TIMEOUT (e.g. 1s) with a remote collector; CI environments where the tracing backend is a stub.","solutions":["Verify the collector at OTEL_EXPORTER_OTLP_ENDPOINT is reachable from Caddy at shutdown time (curl the endpoint's / health path)","Raise OTEL_EXPORTER_OTLP_TIMEOUT (e.g. 10s or 30s) so the final flush can complete","This error is non-fatal for config load — it is logged/returned during cleanup; if spans are still being delivered, it can be treated as a warning about lost tail spans","Ensure only one Caddy instance writes to the same collector path if the collector rejects duplicate connections"],"exampleFix":"# before\nOTEL_EXPORTER_OTLP_TIMEOUT=1s\n\n# after\nOTEL_EXPORTER_OTLP_TIMEOUT=30s","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// During cleanup (e.g. your own wrapper around Caddy runs or module Cleanup):\nif err := provider.Shutdown(ctx); err != nil {\n    // non-fatal: log and continue teardown; buffered tail spans may be lost\n    log.Printf(\"warn: tracer provider shutdown: %v\", err)\n}","preventionTips":["Keep the collector reachable during Caddy reloads/shutdown windows","Set OTEL_EXPORTER_OTLP_TIMEOUT generously (10-30s) so the final flush completes","Treat shutdown errors as data-loss warnings for buffered spans, not as config errors","Avoid rapid successive config reloads that race provider teardown"],"tags":["tracing","opentelemetry","shutdown","flush","lifecycle"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}