kestra-io/kestra · error · CommandLine.ParameterException

Invalid flow path

Error message

Invalid flow path

What it means

Thrown by 'kestra server standalone' when loading --flow-path fails. Same logic and message as the executor command: localFlowRepositoryLoader.load throws IOException, wrapped as a picocli ParameterException 'Invalid flow path' with the IOException as cause. Fires before super.call() and before StandAloneRunner starts.

Source

Thrown at cli/src/main/java/io/kestra/cli/commands/servers/StandAloneCommand.java:117

    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);
        this.ignoreExecutionService.get().setIgnoredIndexerRecords(ignoreIndexerRecords);
        this.ignoreExecutionService.get().setIgnoredQueueRecords(ignoreQueueRecords);

        KestraContext.getContext().injectWorkerConfigs(workerThread);

        if (tenantId != null) {
            tenantIdSelectorService.get().createTenant(tenantId);
        }

        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);
            }
        }

        super.call();

        try (StandAloneRunner standAloneRunner = standAloneRunnerProvider.get()) {

            if (this.workerThread == 0) {
                standAloneRunner.setWorkerEnabled(false);
            } else {
                standAloneRunner.setWorkerThread(this.workerThread);
            }

            if (this.controllerDisabled) {
                standAloneRunner.setControllerEnabled(false);
            }

            if (this.indexerDisabled) {

View on GitHub (pinned to 823fada927)

Solutions

1. Use an absolute path for --flow-path.
2. Confirm the file is readable by the Kestra process user.
3. Pre-validate the flow with 'kestra flow validate'.
4. Read the IOException cause in the stack trace for the exact reason.

Example fix

# before
kestra server standalone --flow-path flows
# after
kestra server standalone --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 standalone with --flow-path <p>; localFlowRepositoryLoader.load(tenantId, p) raises IOException; catch rethrows CommandLine.ParameterException(spec, "Invalid flow path", e).

Common situations: Flow file missing/unreadable, malformed YAML, wrong working directory for a relative path, or permissions issue on a mounted volume.

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