{"record":{"id":"e5d4bff56648fcff","repo":"apache/seatunnel","slug":"sample-dry-run-mode-does-not-support-async","errorCode":null,"errorMessage":"Sample dry-run mode does not support --async.","messagePattern":"Sample dry-run mode does not support --async\\.","errorType":"validation","errorClass":"ParameterException","httpStatus":null,"severity":"error","filePath":"seatunnel-core/seatunnel-starter/src/main/java/org/apache/seatunnel/core/starter/seatunnel/args/ClientCommandArgs.java","lineNumber":277,"sourceCode":"        validateSampleOptions();\n        if (dryRun == DryRun.SAMPLE) {\n            validateSampleMode();\n        }\n    }\n\n    /**\n     * Validates that sample mode runs locally without asynchronous submission, restore, savepoint,\n     * validation, job control, encryption, or decryption options.\n     *\n     * @throws ParameterException when sample mode is combined with an unsupported option\n     */\n    public void validateSampleMode() {\n        if (masterType != MasterType.LOCAL) {\n            throw new ParameterException(\n                    \"Sample dry-run mode requires --master/--deploy-mode local.\");\n        }\n        if (async) {\n            throw new ParameterException(\"Sample dry-run mode does not support --async.\");\n        }\n        if (restoreJobId != null\n                || restoreWithCheckpointJobId != null\n                || savePointJobId != null\n                || checkConfig\n                || listJob\n                || getRunningJobMetrics\n                || jobId != null\n                || cancelJobId != null\n                || forceCancelJobId != null\n                || metricsJobId != null\n                || checkpointOverviewJobId != null\n                || checkpointHistoryJobId != null\n                || encrypt\n                || decrypt) {\n            throw new ParameterException(\n                    \"Sample dry-run mode cannot be combined with validation, job control, restore, savepoint, encryption, or decryption options.\");\n        }","sourceCodeStart":259,"sourceCodeEnd":295,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-core/seatunnel-starter/src/main/java/org/apache/seatunnel/core/starter/seatunnel/args/ClientCommandArgs.java#L259-L295","documentation":"validateSampleMode() throws this ParameterException when --dry-run sample is combined with the --async flag. Sample mode runs synchronously to print sampled records; async submission is incompatible with that flow and is rejected during CLI validation.","triggerScenarios":"Running `seatunnel.sh --dry-run sample ... --async`.","commonSituations":"Scripts built for normal (async) cluster submissions being reused for dry-runs; habitually adding --async to speed up job submission.","solutions":["Remove the --async flag when using --dry-run sample","Use sample mode synchronously and inspect the printed sample output"],"exampleFix":"// before\n--dry-run sample --async\n// after\n--dry-run sample","handlingStrategy":"validation","validationCode":"if (dryRun === 'sample' && async) {\n  throw new Error('--async is not supported with --dry-run sample');\n}","typeGuard":null,"tryCatchPattern":"try {\n  seatunnel.run(args);\n} catch (ParameterException e) {\n  if (e.getMessage().contains('does not support --async')) {\n    args.remove('--async');\n    seatunnel.run(args);\n  } else { throw e; }\n}","preventionTips":["Drop --async whenever running a sample dry-run","Keep async submission scripts separate from dry-run scripts"],"tags":["cli","dry-run","config-conflict"],"backgroundTag":"conflicting-config-options","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}