grpc/grpc-java · error · IllegalArgumentException

Provider not found for ${pluginName}

Error message

Provider not found for ${pluginName}

What it means

CertificateProviderStore.Factory.create looks up a CertificateProviderProvider by the plugin name declared in the xDS certificate_provider_instance config. If certificateProviderRegistry has no provider registered under key.pluginName, it throws IllegalArgumentException. This means the certificate provider plugin referenced by the config is unknown to the client at runtime.

Source

Thrown at xds/src/main/java/io/grpc/xds/internal/security/certprovider/CertificateProviderStore.java:131

          + notifyCertUpdates
          + ", config="
          + config
          + '}';
    }
  }

  private final class CertProviderFactory
      implements ReferenceCountingMap.ValueFactory<CertProviderKey, CertificateProvider> {

    private CertProviderFactory() {
    }

    @Override
    public CertificateProvider create(CertProviderKey key) {
      CertificateProviderProvider certProviderProvider =
          certificateProviderRegistry.getProvider(key.pluginName);
      if (certProviderProvider == null) {
        throw new IllegalArgumentException("Provider not found for " + key.pluginName);
      }
      CertificateProvider certProvider = certProviderProvider.createCertificateProvider(
              key.config, new CertificateProvider.DistributorWatcher(), key.notifyCertUpdates);
      certProvider.start();
      return certProvider;
    }
  }

  @VisibleForTesting
  public CertificateProviderStore(CertificateProviderRegistry certificateProviderRegistry) {
    this.certificateProviderRegistry = certificateProviderRegistry;
    certProviderMap = new ReferenceCountingMap<>(new CertProviderFactory());
  }

  /**
   * Creates or retrieves a {@link CertificateProvider} instance, increments its ref-count and
   * registers the watcher passed. Returns a {@link Handle} that can be {@link Handle#close()}d when
   * the instance is no longer needed by the caller.

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Add the required certificate provider implementation to the classpath (e.g. grpc-xds file watcher provider) and ensure it is registered with the CertificateProviderRegistry used to build the store
2. Fix the plugin_name in the xDS config/bootstrap to match a registered provider exactly
3. Verify gRPC bootstrap certProviders configuration and that providers were passed when constructing CertificateProviderStore
4. Log available registered plugin names to confirm which names are valid at runtime

Example fix

// before: registry built without providers
CertificateProviderStore store = new CertificateProviderStore(/** empty registry **/);
// after
CertificateProviderRegistry registry = CertificateProviderRegistry.emptyRegistry();
registry.register(new FileWatcherCertificateProviderProvider());
CertificateProviderStore store = new CertificateProviderStore(registry);

// Verify plugin name is registered before building config that references it
CertificateProviderProvider p = registry.getProvider(pluginName);
if (p == null) throw new IllegalArgumentException("No certificate provider registered for " + pluginName);

try {
  CertificateProvider cp = storeFactory.create(key);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Provider not found")) {
    logger.error("Unknown cert provider plugin: check bootstrap certProviders and classpath", e);
  }
  throw e;
}

When it happens

Trigger: An xDS config (or bootstrap) references a certificate_provider_instance whose plugin_name is not registered in the CertificateProviderRegistry — e.g. 'file_watcher' or 'envoy.grpc_certificate_providers' support not on the classpath / not passed to the registry when building CertificateProviderStore.

Common situations: Missing grpc-xds cert provider dependencies; custom provider not registered via CertificateProviderProvider registry; typo or version mismatch between plugin_name in config and registered providers; bootstrap omitting certProviders entries.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• CertificateProvider instance name '${certInstanceName}' not
• ca_certificate_provider_instance name '${rootCaInstanceName}
• Fail to read bootstrap file
• No xds servers found for authority
• Matcher tree depth exceeds limit of 16

AI-assisted analysis of grpc/grpc-java@64daddc1f3 (2026-09-08). Data as JSON: /api/errors/eb4c1d276e2877b2. Report an issue: GitHub.