App-vNext/Polly · error · KeyNotFoundException

Unable to find a resilience pipeline associated with the key

Error message

Unable to find a resilience pipeline associated with the key '{key}'. Please ensure that either the resilience pipeline or the builder is registered.

What it means

ResiliencePipelineProvider<TKey>.GetPipeline(key) throws KeyNotFoundException when TryGetPipeline returns false for the given key. The provider is the read-side of the registry; the key must have been registered beforehand either as a built pipeline or as a builder. The message tells you neither the pipeline nor its builder was registered under that key.

Source

Thrown at src/Polly.Core/Registry/ResiliencePipelineProvider.cs:25

/// </summary>
/// <typeparam name="TKey">The type of the key.</typeparam>
public abstract class ResiliencePipelineProvider<TKey>
    where TKey : notnull
{
    /// <summary>
    /// Retrieves a resilience pipeline from the provider using the specified key.
    /// </summary>
    /// <param name="key">The key used to identify the resilience pipeline.</param>
    /// <returns>The resilience pipeline associated with the specified key.</returns>
    /// <exception cref="KeyNotFoundException">Thrown when no resilience pipeline is found for the specified key.</exception>
    public virtual ResiliencePipeline GetPipeline(TKey key)
    {
        if (TryGetPipeline(key, out var pipeline))
        {
            return pipeline;
        }

        throw new KeyNotFoundException($"Unable to find a resilience pipeline associated with the key '{key}'. " +
            $"Please ensure that either the resilience pipeline or the builder is registered.");
    }

    /// <summary>
    /// Retrieves a generic resilience pipeline from the provider using the specified key.
    /// </summary>
    /// <typeparam name="TResult">The type of result that the resilience pipeline handles.</typeparam>
    /// <param name="key">The key used to identify the resilience pipeline.</param>
    /// <returns>The resilience pipeline associated with the specified key.</returns>
    /// <exception cref="KeyNotFoundException">Thrown when no resilience pipeline is found for the specified key.</exception>
    public virtual ResiliencePipeline<TResult> GetPipeline<TResult>(TKey key)
    {
        if (TryGetPipeline<TResult>(key, out var pipeline))
        {
            return pipeline;
        }

        throw new KeyNotFoundException($"Unable to find a generic resilience pipeline of '{typeof(TResult).Name}' associated with the key '{key}'. " +

View on GitHub (pinned to d0e46bdb1e)

Solutions

Register the pipeline or builder under the exact key via registry.TryAddPipeline(...) / TryAddBuilder(...) before resolving.
Use TryGetPipeline(key, out var pipeline) to guard resolution instead of GetPipeline when the key may be absent.
Verify the key value, type, and comparer used by the registry match what you registered.

Example fix

// before
var pipeline = provider.GetPipeline("order-api"); // throws if not registered

// after
registry.TryAddPipeline("order-api", builder => builder.AddRetry(new()));
// later
if (provider.TryGetPipeline("order-api", out var pipeline)) { /* use */ }

Defensive patterns

Strategy: validation

Validate before calling

// Resolve defensively:
if (provider.TryGetPipeline(key, out var pipeline)) {
    // use pipeline
} else {
    // register or handle absence
}

Try / catch

try { var p = provider.GetPipeline(key); }
catch (KeyNotFoundException ex) when (ex.Message.Contains(key)) {
    // log, register on demand, or fall back to a default pipeline
}

Prevention

Register all expected keys at startup (TryAddPipeline/TryAddBuilder) before resolving.
Prefer TryGetPipeline over GetPipeline when absence is a legitimate runtime state.
Centralize key strings as constants to avoid typos.

When it happens

Trigger: Calling registry.GetPipeline("my-key") when only a different key, a generic pipeline, or nothing was registered; looking up by a key that was registered on a different ResiliencePipelineRegistry instance.

Common situations: Typo in the key string; key registered after first resolution (lazy registration ordering); using the wrong registry in multi-tenant setups; registering only a generic pipeline (GetPipeline<TResult>) but calling the non-generic GetPipeline.

Related errors

AI-assisted analysis of App-vNext/Polly@d0e46bdb1e (2026-08-13). Data as JSON: /api/errors/4e78d78c61f6ee8b. Report an issue: GitHub.