quarkusio/quarkus · error · ConfigurationException

Unable to find credentials provider for the mailer {{mailerN

Error message

Unable to find credentials provider for the mailer {{mailerName}}.

What it means

Mailers resolves mail credentials through a CredentialsProvider looked up by bean name via CredentialsProviderFinder. If the finder throws (typically because no provider bean with that name is registered), findCredentialsProvider wraps the failure in this ConfigurationException naming the mailer.

Source

Thrown at extensions/mailer/runtime/src/main/java/io/quarkus/mailer/runtime/Mailers.java:164

            TlsConfigurationRegistry tlsRegistry) {
        io.vertx.ext.mail.MailConfig cfg = toVertxMailConfig(name, config, tlsRegistry);
        MailClientBuilder clientBuilder = MailClient.builder(vertx).with(cfg);
        if (config.credentialsProvider().isPresent()) {
            String beanName = config.credentialsProviderName().orElse(null);
            CredentialsProvider credentialsProvider = findCredentialsProvider(name, beanName);
            String providerName = config.credentialsProvider().get();
            MailCredentialsSupplier credentialsSupplier = new MailCredentialsSupplier(credentialsProvider, providerName);
            clientBuilder.withCredentialsSupplier(credentialsSupplier);
        }
        // Do not create a shared instance, as we want separated connection pool for each SMTP servers.
        return clientBuilder.build();
    }

    private CredentialsProvider findCredentialsProvider(String mailerName, String beanName) {
        try {
            return CredentialsProviderFinder.find(beanName);
        } catch (Exception e) {
            throw new ConfigurationException("Unable to find credentials provider for the mailer " + mailerName + ".", e);
        }
    }

    private io.vertx.ext.mail.DKIMSignOptions toVertxDkimSignOptions(DkimSignOptionsConfig optionsConfig) {
        DKIMSignOptions vertxDkimOptions = new io.vertx.ext.mail.DKIMSignOptions();

        String sdid = optionsConfig.sdid()
                .orElseThrow(() -> {
                    throw new ConfigurationException("Must provide the Signing Domain Identifier (sdid).");
                });
        vertxDkimOptions.setSdid(sdid);

        String selector = optionsConfig.selector()
                .orElseThrow(() -> {
                    throw new ConfigurationException("Must provide the selector.");
                });
        vertxDkimOptions.setSelector(selector);

View on GitHub (pinned to e1c734241f)

Solutions

Register a CredentialsProvider bean with the exact name referenced: a @Named("myProvider") class implementing CredentialsProvider (e.g. @ApplicationScoped).
Verify quarkus.mailer.credentials-provider-name matches the bean's @Name / provider name exactly.
Add the extension providing the provider (e.g. quarkus-vault, or your own module) to the application dependencies.
If no custom provider is needed, remove the credentials-provider-name property and configure username/password directly.

Example fix

// before: config references a provider that does not exist
quarkus.mailer.credentials-provider-name=mailCreds

// after: register the matching bean
@ApplicationScoped
@Named("mailCreds")
public class MailCredsProvider implements CredentialsProvider {
    @Override
    public Credentials getCredentials(CredentialsProviderContext context) {
        return new Credentials("user", "secret");
    }
}

Defensive patterns

Strategy: validation

Validate before calling

// At startup, verify the named provider bean exists before the mailer uses it
boolean found = Arc.container().instance(CredentialsProvider.class)
        .select(NameLiteral.of("mailCreds")).isResolvable();
if (!found) throw new IllegalStateException("CredentialsProvider 'mailCreds' is not registered");

Try / catch

try {
    mailer.send(mail).await().indefinitely();
} catch (ConfigurationException e) {
    if (e.getMessage().startsWith("Unable to find credentials provider")) {
        LOG.error("Check quarkus.mailer.credentials-provider-name and the @Named provider bean", e);
    }
    throw e;
}

Prevention

Keep provider names in a shared constants class referenced by both config and @Named
Add a startup check (StartupEvent observer) that resolves each configured provider
Document the required dependency extension next to the config property

When it happens

Trigger: Setting quarkus.mailer.<mailer>.credentials-provider-name (or credentials-provider bean lookup) to a name for which no CredentialsProvider bean exists; a custom provider failing to initialize inside CredentialsProviderFinder.find(beanName).

Common situations: Typo in the credentials-provider-name config value; the CredentialsProvider bean was removed or not registered as a @Named bean; using named mailers where the provider is only registered for the default mailer; missing a credentials provider extension dependency (e.g. quarkus-credentials or vault).

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/b60f4d12e8705fa9. Report an issue: GitHub.