kestra-io/kestra · error · CommandLine.ParameterException

Invalid flow path

Error message

Invalid flow path

What it means

Thrown by the 'kestra server executor' command when loading the --flow-path fails. localFlowRepositoryLoader.load(...) throws IOException (file not found, unreadable, invalid YAML/flow), which the command wraps in a picocli ParameterException with message 'Invalid flow path'. The original IOException is attached as the cause.

Source

Thrown at cli/src/main/java/io/kestra/cli/commands/servers/ExecutorCommand.java:99

        return ImmutableMap.of(
            "kestra.server-type", ServerType.EXECUTOR
        );
    }

    @Override
    public Integer call() throws Exception {
        this.ignoreExecutionService.get().setIgnoredExecutions(ignoreExecutions);
        this.ignoreExecutionService.get().setIgnoredFlows(ignoreFlows);
        this.ignoreExecutionService.get().setIgnoredNamespaces(ignoreNamespaces);
        this.ignoreExecutionService.get().setIgnoredTenants(ignoreTenants);

        super.call();

        if (flowPath != null) {
            try {
                localFlowRepositoryLoader.get().load(tenantIdSelectorService.get().getTenantId(this.tenantId), this.flowPath);
            } catch (IOException e) {
                throw new CommandLine.ParameterException(this.spec.commandLine(), "Invalid flow path", e);
            }
        }

        executorService.get().run();

        // start the embedded SystemWorker (always present in EXECUTOR mode)
        poolExecutor = executorsUtils.cachedThreadPool("embedded-services");
        log.info("Starting the embedded SystemWorker.");
        poolExecutor.execute(systemWorker.get()::start);

        shutdownHook(true, () -> poolExecutor.shutdown());

        Await.await().forever().until(() -> !this.applicationContext.isRunning());

        return 0;
    }
}

View on GitHub (pinned to 823fada927)

Solutions

1. Pass an absolute path to the flow file/directory.
2. Verify the file exists and is readable by the Kestra user.
3. Validate the YAML (kestra flow validate) before starting the server.
4. Inspect the wrapped IOException cause in the stack trace for the precise failure.

Example fix

# before
kestra server executor --flow-path ./flows
# after
kestra server executor --flow-path /opt/kestra/flows/myflow.yaml

Path p = Path.of(flowPath);
if (!Files.exists(p) || !Files.isReadable(p)) {
  throw new IllegalArgumentException('Flow path does not exist or is not readable: ' + p);
}

try {
  localFlowRepositoryLoader.get().load(tenantId, flowPath);
} catch (IOException e) {
  throw new CommandLine.ParameterException(this.spec.commandLine(), "Invalid flow path", e);
}

When it happens

Trigger: User starts the executor with --flow-path <p>; localFlowRepositoryLoader.load(tenantId, p) throws IOException; the catch rethrows as CommandLine.ParameterException(spec, "Invalid flow path", e).

Common situations: Path does not exist, path is a directory the loader cannot traverse, file permissions deny read, YAML is malformed or references a missing namespace, or the path is relative to a different working directory.

Related errors

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

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