SigNoz/signoz · error

error fetching metric metadata: %s

Error message

error fetching metric metadata: %s

What it means

Thrown by SigNoz query-service ClickHouse reader when GetUpdatedMetricsMetadata fails to load metric metadata (from cache or the metadata DB) for a metric name. The wrapped apiError carries the underlying cause, typically a DB connectivity or missing metadata table issue. It aborts downstream metric operations such as histogram bucket queries that depend on temporality/isMonotonic metadata.

Source

Thrown at pkg/query-service/app/clickhouseReader/reader.go:3241

	}

	return &attributeValues, nil
}

func (r *ClickHouseReader) GetMetricMetadata(ctx context.Context, orgID valuer.UUID, metricName, serviceName string) (*v3.MetricMetadataResponse, error) {

	ctx = ctxtypes.NewContextWithCommentVals(ctx, map[string]string{
		instrumentationtypes.TelemetrySignal:  telemetrytypes.SignalMetrics.StringValue(),
		instrumentationtypes.CodeNamespace:    "clickhouse-reader",
		instrumentationtypes.CodeFunctionName: "GetMetricMetadata",
	})
	unixMilli := common.PastDayRoundOff()

	// 1. Fetch metadata from cache/db using unified function
	metadataMap, apiError := r.GetUpdatedMetricsMetadata(ctx, orgID, metricName)
	if apiError != nil {
		r.logger.Error("Error in getting metric cached metadata", errorsV2.Attr(apiError))
		return nil, fmt.Errorf("error fetching metric metadata: %s", apiError.Err.Error())
	}

	// Defaults in case metadata is not found
	var (
		deltaExists bool
		isMonotonic bool
		temporality string
		description string
		metricType  string
		unit        string
	)

	metadata, ok := metadataMap[metricName]
	if !ok {
		return nil, fmt.Errorf("metric metadata not found: %s", metricName)
	}

	metricType = string(metadata.MetricType)

View on GitHub (pinned to 5069bf80b0)

Solutions

1. Verify ClickHouse and the metadata store are reachable from the query-service (check CLICKHOUSE_URL / storage config)
2. Inspect query-service logs for the wrapped apiError to identify the true cause
3. Confirm the metric name exists (it was recently ingested) by querying the time_series table directly
4. Re-run metadata migrations or wait for the metadata cache refresh cycle if the metric is brand new

Example fix

// before
metadataMap, apiError := r.GetUpdatedMetricsMetadata(ctx, orgID, metricName)
if apiError != nil {
    return nil, fmt.Errorf("error fetching metric metadata: %s", apiError.Err.Error())
}

// after: fall back to defaults so the caller can still proceed
metadataMap, apiError := r.GetUpdatedMetricsMetadata(ctx, orgID, metricName)
if apiError != nil {
    r.logger.Error("metadata lookup failed, using defaults", errorsV2.Attr(apiError))
    metadataMap = map[string]v3.MetricMetadata{}
}

// Precheck metadata availability
if _, apiErr := reader.GetUpdatedMetricsMetadata(ctx, orgID, metricName); apiErr != nil {
    log.Warn("metadata unavailable", apiErr)
}

// In Go: wrap the call, inspect error, degrade gracefully
if err := svc.FetchMetricMeta(ctx, orgID, name); err != nil {
    if strings.Contains(err.Error(), "error fetching metric metadata") {
        // fallback to defaults / retry later
    }
}

When it happens

Trigger: Calling a metrics API endpoint (e.g. histogram bucket listing / metric metadata dependent handlers) when the metrics metadata table is unreachable, empty, or the cache layer returns an API error for the orgID+metricName pair.

Common situations: Fresh SigNoz install where the metadata migration hasn't run; ClickHouse/Postgres down or misconfigured (SQLEX or CH default); orgID mismatch after changing auth config; upgrading SigNoz versions where the metadata table schema changed.

Related errors

• CodeLicenseUnavailable
• CodeForbidden
• CodeNotFound
• ErrCodeInvalidState
• CodeLicenseUnavailable

AI-assisted analysis of SigNoz/signoz@5069bf80b0 (2026-08-28). Data as JSON: /api/errors/993355eb5f2c15fc. Report an issue: GitHub.