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 list' when no plugins path is configured. Unlike install, list always requires a path; if pluginsPath is null the command throws a picocli ParameterException referencing --plugins or KESTRA_PLUGINS_PATH. Same wording (and same missing closing quote) as the install command.

Source

Thrown at cli/src/main/java/io/kestra/cli/commands/plugins/PluginListCommand.java:34

    name = "list",
    description = "List all plugins already installed"
)
public class PluginListCommand extends AbstractCommand {
    @Spec
    CommandLine.Model.CommandSpec spec;

    @Option(names = { "--core" }, description = "Also write core tasks plugins")
    private boolean core = false;

    @Inject
    ApplicationContext applicationContext; // force injection of beans in AbstractCommand

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

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

        List<RegisteredPlugin> plugins = core ? pluginRegistry.plugins() : pluginRegistry.externalPlugins();
        plugins.forEach(registeredPlugin -> stdOut(registeredPlugin.toString()));

        return 0;
    }
}

View on GitHub (pinned to 823fada927)

Solutions

1. Set KESTRA_PLUGINS_PATH=/path/to/plugins in the environment before running.
2. Pass --plugins /path/to/plugins on the kestra root command.
3. Confirm the directory exists and contains the unpacked external plugins.

Example fix

# before
kestra plugins list
# after
export KESTRA_PLUGINS_PATH=/app/plugins
kestra plugins list

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

When it happens

Trigger: User runs 'kestra plugins list' (or with --core) without --plugins set and without KESTRA_PLUGINS_PATH in the environment; this.pluginsPath is null and the guard fires.

Common situations: Running plugins list on a server where the path is set via config file but the command reads only the option/env, env var not exported in the current shell, or a fresh container without the variable.

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/ad39e109ddf2b96d. Report an issue: GitHub.