grpc/grpc-go · error

no ObservabilityConfig found

Error message

no ObservabilityConfig found

What it means

observability.Start found no config: neither GRPC_GCP_OBSERVABILITY_CONFIG nor GRPC_GCP_OBSERVABILITY_CONFIG_FILE was set (or both empty), so parseObservabilityConfig returned nil and Start refuses to continue. This is a usage error — Start is opt-in and requires one of the env vars.

Solutions

1. Set GRPC_GCP_OBSERVABILITY_CONFIG to a JSON config string or GRPC_GCP_OBSERVABILITY_CONFIG_FILE to a file path before calling Start.
2. If you did not intend to use observability, remove the Start call entirely.
3. If using a scheduler, ensure the env var is in the container spec and is exported.
4. Print os.Environ() in startup logs to confirm which grpc_* vars are visible to the process.

Example fix

// before
observability.Start(ctx)

// after
export GRPC_GCP_OBSERVABILITY_CONFIG='{"project_id":"my-proj","cloud_logging":{"client_rpc_events":[{"methods":["*"]}]}}'
observability.Start(ctx)

if os.Getenv("GRPC_GCP_OBSERVABILITY_CONFIG") == "" && os.Getenv("GRPC_GCP_OBSERVABILITY_CONFIG_FILE") == "" {
    return errors.New("set GRPC_GCP_OBSERVABILITY_CONFIG or GRPC_GCP_OBSERVABILITY_CONFIG_FILE, or remove the observability.Start call")
}

if err := observability.Start(ctx); err != nil {
    if strings.Contains(err.Error(), "no ObservabilityConfig found") {
        // either set the env or remove the Start call
        return fmt.Errorf("observability opted-in but no config env var set: %w", err)
    }
    return err
}

When it happens

Trigger: Calling observability.Start(ctx) in a process where both env vars are unset. Emitted at observability.go:54.

Common situations: Forgetting to set the env var in the deployment manifest; setting it under a slightly different name (e.g. GRPC_OBSERVABILITY_CONFIG); env var set in a parent shell but not exported into the systemd unit / container; intent was to disable observability, in which case Start should not be called.

Related errors

• error reading observability configuration file
• cannot have a leading slash
• cannot have exclude and a '*' wildcard
• empty destination project ID
• error in clientRPCEvent method

AI-assisted analysis of grpc/grpc-go@0c51461d27 (2026-08-11). Data as JSON: /api/errors/0be5acf756aa0c20. Report an issue: GitHub.

Appendix: source

Thrown at gcp/observability/observability.go:54

// Start is the opt-in API for gRPC Observability plugin. This function should
// be invoked in the main function, and before creating any gRPC clients or
// servers, otherwise, they might not be instrumented. At high-level, this
// module does the following:
//
//   - it loads observability config from environment;
//   - it registers default exporters if not disabled by the config;
//   - it sets up telemetry collectors (binary logging sink or StatsHandlers).
//
// Note: this method should only be invoked once.
// Note: handle the error
func Start(ctx context.Context) error {
	config, err := parseObservabilityConfig()
	if err != nil {
		return err
	}
	if config == nil {
		return fmt.Errorf("no ObservabilityConfig found")
	}

	// Set the project ID if it isn't configured manually.
	if err = ensureProjectIDInObservabilityConfig(ctx, config); err != nil {
		return err
	}

	// Cleanup any created resources this function created in case this function
	// errors.
	defer func() {
		if err != nil {
			End()
		}
	}()

	// Enabling tracing and metrics via OpenCensus
	if err = startOpenCensus(config); err != nil {
		return fmt.Errorf("failed to instrument OpenCensus: %v", err)

View on GitHub (pinned to 0c51461d27)