{"record":{"id":"32452a0973ea38fd","repo":"SigNoz/signoz","slug":"error-querying-time-series-v4-to-get-metrics-metad","errorCode":null,"errorMessage":"error querying time_series_v4 to get metrics metadata: %v","messagePattern":"error querying time_series_v4 to get metrics metadata: (.+?)","errorType":"exception","errorClass":"model.ApiError","httpStatus":500,"severity":"error","filePath":"pkg/query-service/app/clickhouseReader/reader.go","lineNumber":5227,"sourceCode":"\t\tmetricList := \"'\" + strings.Join(stillMissing, \"', '\") + \"'\"\n\t\treductionEnabled := r.fl.BooleanOrEmpty(ctx, flagger.FeatureEnableMetricsReduction, featuretypes.NewFlaggerEvaluationContext(orgID))\n\t\tvar query string\n\t\tif reductionEnabled {\n\t\t\tquery = fmt.Sprintf(`SELECT DISTINCT metric_name, type, description, temporality, is_monotonic, unit\n\t\t\tFROM (\n\t\t\t\tSELECT metric_name, type, description, temporality, is_monotonic, unit FROM %s.%s WHERE metric_name IN (%s)\n\t\t\t\tUNION ALL\n\t\t\t\tSELECT metric_name, type, description, temporality, is_monotonic, unit FROM %s.%s WHERE metric_name IN (%s)\n\t\t\t)`, signozMetricDBName, signozTSTableNameV4, metricList, signozMetricDBName, signozTSTableNameV4Reduced, metricList)\n\t\t} else {\n\t\t\tquery = fmt.Sprintf(`SELECT DISTINCT metric_name, type, description, temporality, is_monotonic, unit\n\t\t\tFROM %s.%s\n\t\t\tWHERE metric_name IN (%s)`, signozMetricDBName, signozTSTableNameV4, metricList)\n\t\t}\n\t\tvalueCtx := context.WithValue(ctx, \"clickhouse_max_threads\", constants.MetricsExplorerClickhouseThreads)\n\t\trows, err := r.db.Query(valueCtx, query)\n\t\tif err != nil {\n\t\t\treturn cachedMetadata, &model.ApiError{Typ: \"ClickhouseErr\", Err: fmt.Errorf(\"error querying time_series_v4 to get metrics metadata: %v\", err)}\n\t\t}\n\t\tdefer rows.Close()\n\t\tfor rows.Next() {\n\t\t\tmetadata := new(model.UpdateMetricsMetadata)\n\t\t\tif err := rows.Scan(\n\t\t\t\t&metadata.MetricName,\n\t\t\t\t&metadata.MetricType,\n\t\t\t\t&metadata.Description,\n\t\t\t\t&metadata.Temporality,\n\t\t\t\t&metadata.IsMonotonic,\n\t\t\t\t&metadata.Unit,\n\t\t\t); err != nil {\n\t\t\t\treturn cachedMetadata, &model.ApiError{Typ: \"ClickhouseErr\", Err: fmt.Errorf(\"error scanning fallback metadata: %v\", err)}\n\t\t\t}\n\n\t\t\tcacheKey := constants.UpdatedMetricsMetadataCachePrefix + metadata.MetricName\n\t\t\tif cacheErr := r.cache.Set(ctx, orgID, cacheKey, metadata, 0); cacheErr != nil {\n\t\t\t\tr.logger.Error(\"Failed to cache fallback metadata\", \"metric_name\", metadata.MetricName, errorsV2.Attr(cacheErr))","sourceCodeStart":5209,"sourceCodeEnd":5245,"githubUrl":"https://github.com/SigNoz/signoz/blob/5069bf80b08f1f00d7e014eccc09902f9871004f/pkg/query-service/app/clickhouseReader/reader.go#L5209-L5245","documentation":"Thrown by ClickHouseReader when the ClickHouse query against time_series_v4 (metrics metadata fallback) fails. This is a database-level failure: connection problems, syntax errors from malformed metric names, or a missing table/database in the deployed SigNoz schema. The error wraps the underlying ClickHouse driver error with %v.","triggerScenarios":"Calling GetMetricsMetadata (or an API that populates metrics metadata for the explorer) where r.db.Query on 'SELECT ... FROM signoz_metrics.time_series_v4 WHERE metric_name IN (...)' fails: ClickHouse is down/unreachable, signoz_metric_db_name or the v4 table does not exist (older SigNoz schema), or metricList is empty/malformed producing invalid SQL.","commonSituations":"ClickHouse connection misconfiguration (host/port/credentials in signoz config), upgrading SigNoz from a pre-v4 schema where time_series_v4 was not yet created, ClickHouse node restarted or out of resources, or a migration that renamed the metrics DB/table.","solutions":["Verify ClickHouse is reachable and credentials in the query-service config are correct","Check that the database/table in signoz_metric_db_name (default signoz_metrics) and time_series_v4 exist: SHOW TABLES FROM signoz_metrics","Inspect query-service logs for the wrapped %v driver error to identify the exact ClickHouse failure","If the v4 table is missing, run SigNoz schema migrations or upgrade to a consistent version","Retry the metrics metadata request once ClickHouse is healthy"],"exampleFix":"// before\nrows, err := r.db.Query(valueCtx, query)\nif err != nil {\n    return cachedMetadata, &model.ApiError{Typ: \"ClickhouseErr\", Err: fmt.Errorf(\"error querying time_series_v4 to get metrics metadata: %v\", err)}\n}\n\n// after (include query context in the error for diagnosability)\nrows, err := r.db.Query(valueCtx, query)\nif err != nil {\n    r.logger.Error(\"time_series_v4 metadata query failed\", \"query\", query, errorsV2.Attr(err))\n    return cachedMetadata, &model.ApiError{Typ: \"ClickhouseErr\", Err: fmt.Errorf(\"error querying time_series_v4 to get metrics metadata: %v\", err)}\n}","handlingStrategy":"retry","validationCode":"// Pre-flight: verify ClickHouse reachable and table exists before requesting metadata\nif err := pingClickhouse(); err != nil { log.Fatal(\"clickhouse unreachable: \", err) }\nif _, err := ch.Query(\"SELECT 1 FROM signoz_metrics.time_series_v4 LIMIT 1\"); err != nil { log.Fatal(\"time_series_v4 missing: \", err) }","typeGuard":null,"tryCatchPattern":"// Treat ClickhouseErr as transient: backoff-retry up to 3 times, then surface to caller\nvar apiErr *model.ApiError\nif errors.As(err, &apiErr) && apiErr.Typ == \"ClickhouseErr\" {\n    if ok := retry(3, time.Second, func() error { _, e := getMetricsMetadata(ctx); return e }); !ok {\n        return fmt.Errorf(\"metrics metadata unavailable: %w\", err)\n    }\n}","preventionTips":["Monitor ClickHouse health and table existence with a readiness probe","Keep query-service and ClickHouse schema versions aligned via migrations","Cache metrics metadata to reduce repeated time_series_v4 queries"],"tags":["clickhouse","metrics-metadata","database-query","signoz"],"backgroundTag":"database-query-failed","analyzedSha":"5069bf80b08f1f00d7e014eccc09902f9871004f","analyzedAt":"2026-08-28T06:22:12.824Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}