{"record":{"id":"78497dcfd3c82b43","repo":"kestra-io/kestra","slug":"missing-required-options-plugins-or-environmen","errorCode":null,"errorMessage":"Missing required options '--plugins' or environment variable 'KESTRA_PLUGINS_PATH","messagePattern":"Missing required options '--plugins' or environment variable 'KESTRA_PLUGINS_PATH","errorType":"validation","errorClass":"CommandLine.ParameterException","httpStatus":null,"severity":"error","filePath":"cli/src/main/java/io/kestra/cli/commands/plugins/PluginInstallCommand.java","lineNumber":60,"sourceCode":"\n    @Option(names = { \"--repositories\" }, description = \"URL to additional Maven repositories\")\n    private URI[] repositories;\n\n    @Spec\n    CommandLine.Model.CommandSpec spec;\n\n    @Inject\n    Provider<MavenPluginDownloader> mavenPluginRepositoryProvider;\n\n    @Inject\n    Provider<PluginCatalogService> pluginCatalogService;\n\n    @Override\n    public Integer call() throws Exception {\n        super.call();\n\n        if (this.locally && this.pluginsPath == null) {\n            throw new CommandLine.ParameterException(\n                this.spec.commandLine(), \"Missing required options '--plugins' \" +\n                    \"or environment variable 'KESTRA_PLUGINS_PATH\"\n            );\n        }\n\n        List<MavenPluginRepositoryConfig> repositoryConfigs = List.of();\n        if (repositories != null) {\n            repositoryConfigs = Arrays.stream(repositories)\n                .map(uri ->\n                {\n                    MavenPluginRepositoryConfig.MavenPluginRepositoryConfigBuilder builder = MavenPluginRepositoryConfig\n                        .builder()\n                        .id(IdUtils.create());\n\n                    String userInfo = uri.getUserInfo();\n                    if (userInfo != null) {\n                        String[] userInfoParts = userInfo.split(\":\");\n                        builder = builder.basicAuth(","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/kestra-io/kestra/blob/823fada9274c4f9c251ea0a516460a4f7d958032/cli/src/main/java/io/kestra/cli/commands/plugins/PluginInstallCommand.java#L42-L78","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set --plugins /path/to/plugins on the kestra command (root-level option).","Export KESTRA_PLUGINS_PATH=/path/to/plugins in the shell or container env before running.","Ensure the directory exists and is writable by the Kestra process.","In Docker, add -e KESTRA_PLUGINS_PATH=/app/plugins and mount the volume."],"exampleFix":"# before\nkestra plugins install io.kestra.plugin:plugin-aws --locally\n# after\nexport KESTRA_PLUGINS_PATH=/app/plugins\nkestra plugins install io.kestra.plugin:plugin-aws --locally","handlingStrategy":"validation","validationCode":"if (this.locally && this.pluginsPath == null) {\n  throw new IllegalStateException('Set --plugins or KESTRA_PLUGINS_PATH before installing locally');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always export KESTRA_PLUGINS_PATH in the Kestra runtime environment.","In containers, set the env var and mount a writable volume.","Confirm the plugins directory is writable before install."],"tags":["cli","plugins","install","usage","configuration"],"backgroundTag":null,"analyzedSha":"823fada9274c4f9c251ea0a516460a4f7d958032","analyzedAt":"2026-08-14T06:15:17.947Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}