kestra-io/kestra · error · CommandLine.ParameterException

Missing required options '--plugins' or environment variable

Error message

Missing required options '--plugins' or environment variable 'KESTRA_PLUGINS_PATH

What it means

Thrown by 'kestra plugins install' (local install mode) when no plugins path is configured. With --locally set and pluginsPath null, the command cannot know where to install, so it throws a picocli ParameterException pointing to the --plugins option or the KESTRA_PLUGINS_PATH env var. Note: the message text is missing its closing single-quote (cosmetic bug).

Source

Thrown at cli/src/main/java/io/kestra/cli/commands/plugins/PluginInstallCommand.java:60

    @Option(names = { "--repositories" }, description = "URL to additional Maven repositories")
    private URI[] repositories;

    @Spec
    CommandLine.Model.CommandSpec spec;

    @Inject
    Provider<MavenPluginDownloader> mavenPluginRepositoryProvider;

    @Inject
    Provider<PluginCatalogService> pluginCatalogService;

    @Override
    public Integer call() throws Exception {
        super.call();

        if (this.locally && this.pluginsPath == null) {
            throw new CommandLine.ParameterException(
                this.spec.commandLine(), "Missing required options '--plugins' " +
                    "or environment variable 'KESTRA_PLUGINS_PATH"
            );
        }

        List<MavenPluginRepositoryConfig> repositoryConfigs = List.of();
        if (repositories != null) {
            repositoryConfigs = Arrays.stream(repositories)
                .map(uri ->
                {
                    MavenPluginRepositoryConfig.MavenPluginRepositoryConfigBuilder builder = MavenPluginRepositoryConfig
                        .builder()
                        .id(IdUtils.create());

                    String userInfo = uri.getUserInfo();
                    if (userInfo != null) {
                        String[] userInfoParts = userInfo.split(":");
                        builder = builder.basicAuth(

View on GitHub (pinned to 823fada927)

Solutions

1. Set --plugins /path/to/plugins on the kestra command (root-level option).
2. Export KESTRA_PLUGINS_PATH=/path/to/plugins in the shell or container env before running.
3. Ensure the directory exists and is writable by the Kestra process.
4. In Docker, add -e KESTRA_PLUGINS_PATH=/app/plugins and mount the volume.

Example fix

# before
kestra plugins install io.kestra.plugin:plugin-aws --locally
# after
export KESTRA_PLUGINS_PATH=/app/plugins
kestra plugins install io.kestra.plugin:plugin-aws --locally

if (this.locally && this.pluginsPath == null) {
  throw new IllegalStateException('Set --plugins or KESTRA_PLUGINS_PATH before installing locally');
}

When it happens

Trigger: User runs 'plugins install <artifact> --locally' without having set --plugins on the root command or the KESTRA_PLUGINS_PATH environment variable; this.pluginsPath is null and the guard fires.

Common situations: Fresh install without KESTRA_PLUGINS_PATH exported, --plugins passed only on a sibling command, env var not propagated into the shell/session, or container missing the env.

Related errors

• Missing required options '--plugins' or environment variable
• Invalid key pair value for inputs
• Too many flow found, need 1, found {}
• Invalid flow path
• Invalid flow path

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