What causes "error shutting down OpenTelemetry: %w" in googleapis/mcp-toolbox?

Inspect the wrapped root cause for the failing exporter

error shutting down OpenTelemetry

Error message

error shutting down OpenTelemetry: %w

What it means

This error is produced by the shutdownFunc closure created in Setup: when the OpenTelemetry shutdown hook (otelShutdown, which flushes and shuts down tracer/meter providers) returns an error, it is wrapped with this message. It occurs at process shutdown, not startup, and typically means telemetry data could not be flushed.

Solutions

Inspect the wrapped root cause for the failing exporter
Ensure the shutdown context allows enough time for flushing (avoid immediate cancellation)
Check network connectivity to the OTLP collector at exit
Treat as non-fatal if telemetry loss at exit is acceptable — the shutdown error is logged and propagated

Defensive patterns

Strategy: try-catch

Try / catch

defer func() {
    if err := otelShutdown(ctx); err != nil {
        logger.WarnContext(ctx, "otel shutdown: %v", err) // tolerate, don't crash
    }
}()

Prevention

Allow sufficient time for flushing on shutdown (avoid instant SIGKILL)
Monitor collector availability so spans can flush before exit
Accept and log shutdown flush errors as non-fatal in wrappers

When it happens

Trigger: Calling otelShutdown(ctx) during graceful shutdown when an OTLP/GCP exporter fails to flush remaining spans or the provider shutdown returns an error (e.g., shutdown context canceled, exporter network error).

Common situations: Fast SIGINT/SIGTERM leaving no time to flush spans to a slow OTLP endpoint, network outage when the process exits, or the shutdown context being canceled before exporters finish.

Related errors

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/fb672743fe60e3bc. Report an issue: GitHub.

Appendix: source

Thrown at cmd/internal/options.go:119

	ctx = util.WithLogger(ctx, logger)
	opts.Logger = logger

	ctx = util.WithIgnoreUnknownTools(ctx, opts.Cfg.IgnoreUnknownTools)

	logger.InfoContext(ctx, fmt.Sprintf("Starting MCP Toolbox for Databases version %s", opts.Cfg.Version))

	// Set up OpenTelemetry
	otelShutdown, err := telemetry.SetupOTel(ctx, opts.Cfg.Version, opts.Cfg.TelemetryOTLP, opts.Cfg.TelemetryGCP, opts.Cfg.TelemetryGCPProject, opts.Cfg.TelemetryServiceName)
	if err != nil {
		errMsg := fmt.Errorf("error setting up OpenTelemetry: %w", err)
		logger.ErrorContext(ctx, errMsg.Error())
		return ctx, nil, errMsg
	}

	shutdownFunc := func(ctx context.Context) error {
		err := otelShutdown(ctx)
		if err != nil {
			errMsg := fmt.Errorf("error shutting down OpenTelemetry: %w", err)
			logger.ErrorContext(ctx, errMsg.Error())
			return err
		}
		return nil
	}

	instrumentation, err := telemetry.CreateTelemetryInstrumentation(opts.Cfg.Version)
	if err != nil {
		errMsg := fmt.Errorf("unable to create telemetry instrumentation: %w", err)
		logger.ErrorContext(ctx, errMsg.Error())
		return ctx, shutdownFunc, errMsg
	}

	ctx = util.WithInstrumentation(ctx, instrumentation)

	return ctx, shutdownFunc, nil
}

View on GitHub (pinned to 8cc6e09de2)