kestra-io/kestra · critical · IllegalArgumentException

Both username and password must be provided if either is pre

Error message

Both username and password must be provided if either is present: please configure both 'kestra.tasks.sdk.authentication.username' and 'kestra.tasks.sdk.authentication.password' properties

What it means

Thrown while constructing the `RunContextSDKFactory`'s default authentication when the SDK auth config has only ONE of `kestra.tasks.sdk.authentication.username` / `kestra.tasks.sdk.authentication.password` set (the other is blank or absent). Both must be present together; an API token alone is also valid (handled separately) but a lone username or lone password is not. Thrown as `IllegalArgumentException` during bean construction, so it fails application startup.

Source

Thrown at core/src/main/java/io/kestra/core/runners/RunContextSDKFactory.java:39

        SDKImpl(ApplicationContext applicationContext) {
            this.sdkAuthentication = applicationContext.getProperty(API_TOKEN_PROP, String.class)
                .map(it -> new SDK.Auth(Optional.of(it), Optional.empty(), Optional.empty()))
                .orElseGet(() ->
                {
                    Optional<String> maybeUserName = applicationContext
                        .getProperty(USERNAME_PROP, String.class)
                        .filter(username -> !username.isBlank()); // to avoid Optional.of("")

                    Optional<String> maybePassword = applicationContext
                        .getProperty(PASSWORD_PROP, String.class)
                        .filter(password -> !password.isBlank()); // to avoid Optional.of("")

                    if (maybePassword.isPresent() && maybeUserName.isPresent()) {
                        return new SDK.Auth(Optional.empty(), maybeUserName, maybePassword);
                    }
                    if (maybeUserName.isPresent() || maybePassword.isPresent()) {
                        throw new IllegalArgumentException(
                            "Both username and password must be provided if either is present: please configure both '" + USERNAME_PROP + "' and '" + PASSWORD_PROP + "' properties"
                        );
                    }
                    return null;
                });
        }

        @Override
        public Optional<Auth> defaultAuthentication() {
            return Optional.ofNullable(this.sdkAuthentication);
        }
    }
}

View on GitHub (pinned to 823fada927)

Solutions

Set BOTH `kestra.tasks.sdk.authentication.username` and `kestra.tasks.sdk.authentication.password`.
Or remove both and use `kestra.tasks.sdk.authentication.api-token` instead.
Or remove all three to run without default SDK auth.
Check for partial env-var overrides (e.g. only `KESTRA_TASKS_SDK_AUTHENTICATION_USERNAME` exported).

Example fix

# before — only username set
kestra:
  tasks:
    sdk:
      authentication:
        username: admin

# after — both set
kestra:
  tasks:
    sdk:
      authentication:
        username: admin
        password: ${SECRET_PASSWORD}
# or use an API token instead
#       api-token: ${SDK_API_TOKEN}

Defensive patterns

Strategy: validation

Validate before calling

// In config validation at startup
boolean hasUser = !isBlank(cfg.username);
boolean hasPass = !isBlank(cfg.password);
boolean hasToken = !isBlank(cfg.apiToken);
if ((hasUser ^ hasPass) && !hasToken) {
    throw new IllegalArgumentException(
        "Configure both username and password, or use api-token, for kestra.tasks.sdk.authentication");
}

Prevention

Set username AND password together, or use api-token alone.
Source secrets from the same vault/env source so one is never missing.
Add a config linter that flags half-set auth pairs before deploy.

When it happens

Trigger: Configuring `kestra.tasks.sdk.authentication.username` without `.password`, or vice-versa, in `application.yml`. Because the check runs in the `SDKImpl` constructor (a `@Singleton` bean), the error surfaces at Micronaut context startup — Kestra will fail to boot.

Common situations: Setting up script/task SDK auth and forgetting one half of the basic-auth pair; migrating from API-token auth to username/password and leaving a stale property; environment-variable override that only sets one of the two.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of kestra-io/kestra@823fada927 (2026-08-14). Data as JSON: /api/errors/e3c2c508b58f477e. Report an issue: GitHub.