microsoft/aspire · error

Instrument name is required.

Error message

Instrument name is required.

What it means

Aspire Dashboard's telemetry repository caches metrics by instrument name. When an incoming OTLP metric arrives, GetOrAddCachedInstrument first asserts the metric has a non-empty Name; a metric without an instrument name cannot be keyed in the cache or stored in the database, so it throws InvalidOperationException to reject malformed ingest data.

Solutions

1. Fix the emitter so every OTLP Metric sets Name before export (e.g. ensure the meter/instrument name is non-empty in your instrumentation library).
2. Inspect the sending SDK/collector configuration to find why a metric is created without a name.
3. If exporting hand-built protobuf, validate Name before calling Export.
4. Wrap dashboard ingest processing so the exception is logged with the resource/scope context instead of aborting the whole batch.

Example fix

// before (client emitting unnamed metric)
var counter = meter.CreateCounter<long>("", "requests");
// after
var counter = meter.CreateCounter<long>("app.requests.count", "requests");

if (string.IsNullOrEmpty(metric.Name))
{
    // skip or fix before calling dashboard ingest
    return;
}

static bool HasInstrumentName(OtlpCollector.Metrics.V1.Metric m) => !string.IsNullOrEmpty(m.Name);

When it happens

Trigger: An OTLP ExportMetricsServiceRequest contains a metric whose Name field is null or empty; AddMetricToDatabase calls GetOrAddCachedInstrument and the string.IsNullOrEmpty(metric.Name) guard fires.

Common situations: A custom or misconfigured instrumentation library emits an unnamed metric; a proxy/collector strips or mangles metric names; hand-crafted OTLP protobuf payloads or tests send metrics with only display names set.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Dimension limit of reached.
• Histogram data point has bucket counts without any explicit…
• Histogram data point sum must be finite.
• Instrument limit of reached. Instrument ' ' will not be…
• Metric data point has no value.

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/7cb99876db5d9f4a. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Dashboard/Otlp/Storage/SqliteTelemetryRepository.Caching.cs:271

                    cachedScope = GetOrAddCachedScope(scopeId, incomingScope.Name, incomingScope.Version, incomingScope.Attributes);
                }
            }

            return AddCachedScope(resource, cachedScope, telemetryType);
        }
    }

    private CachedInstrument GetOrAddCachedInstrument(
        SqliteConnection connection,
        IDbTransaction transaction,
        CachedResource resource,
        CachedResourceView resourceView,
        CachedResourceScope resourceScope,
        Metric metric)
    {
        if (string.IsNullOrEmpty(metric.Name))
        {
            throw new InvalidOperationException("Instrument name is required.");
        }

        lock (_cacheLock)
        {
            if (resourceScope.Instruments.TryGetValue(metric.Name, out var instrument))
            {
                return instrument;
            }

            EnsureCachedInstrumentsLoaded(connection, transaction, resource, resourceScope);
            if (resourceScope.Instruments.TryGetValue(metric.Name, out instrument))
            {
                return instrument;
            }

            var instrumentCount = resource.InstrumentCount ??= connection.QuerySingle<int>(
                    "SELECT COUNT(*) FROM telemetry_metric_instruments WHERE resource_id = @ResourceId;",
                    new { resource.ResourceId },

View on GitHub (pinned to 25830f84bd)