{"record":{"id":"c0381ecc108f6bfb","repo":"conductor-oss/conductor","slug":"workflowdefinition-must-be-either-null-or-workflo","errorCode":null,"errorMessage":"workflowDefinition must be either null, or WorkflowDef, or a valid DSL string","messagePattern":"workflowDefinition must be either null, or WorkflowDef, or a valid DSL string","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"common/src/main/java/com/netflix/conductor/common/metadata/workflow/SubWorkflowParams.java","lineNumber":167,"sourceCode":"     */\n    @JsonSetter(\"workflowDefinition\")\n    public void setWorkflowDefinition(Object workflowDef) {\n        if (workflowDef == null) {\n            this.workflowDefinition = workflowDef;\n        } else if (workflowDef instanceof WorkflowDef) {\n            this.workflowDefinition = workflowDef;\n        } else if (workflowDef instanceof String) {\n            if (!(((String) workflowDef).startsWith(\"${\"))\n                    || !(((String) workflowDef).endsWith(\"}\"))) {\n                throw new IllegalArgumentException(\n                        \"workflowDefinition is a string, but not a valid DSL string\");\n            } else {\n                this.workflowDefinition = workflowDef;\n            }\n        } else if (workflowDef instanceof LinkedHashMap) {\n            this.workflowDefinition = TaskUtils.convertToWorkflowDef(workflowDef);\n        } else {\n            throw new IllegalArgumentException(\n                    \"workflowDefinition must be either null, or WorkflowDef, or a valid DSL string\");\n        }\n    }\n\n    @Override\n    public boolean equals(Object o) {\n        if (this == o) {\n            return true;\n        }\n        if (o == null || getClass() != o.getClass()) {\n            return false;\n        }\n        SubWorkflowParams that = (SubWorkflowParams) o;\n        return Objects.equals(getName(), that.getName())\n                && Objects.equals(getVersion(), that.getVersion())\n                && Objects.equals(getTaskToDomain(), that.getTaskToDomain())\n                && Objects.equals(getWorkflowDefinition(), that.getWorkflowDefinition())\n                && Objects.equals(idempotencyKey, that.idempotencyKey)","sourceCodeStart":149,"sourceCodeEnd":185,"githubUrl":"https://github.com/conductor-oss/conductor/blob/cf7c3e4a8adfb158be778ab1ec525323c363cd3a/common/src/main/java/com/netflix/conductor/common/metadata/workflow/SubWorkflowParams.java#L149-L185","documentation":"SubWorkflowParams.setWorkflowDefinition only accepts null, a WorkflowDef, a '${...}' DSL String, or a LinkedHashMap (converted to a WorkflowDef). Any other runtime type - number, boolean, plain HashMap, array/List - reaches the final else branch and throws this IllegalArgumentException.","triggerScenarios":"Sending the 'workflowDefinition' JSON field as a scalar (int/boolean), an array, or a non-LinkedHashMap map type that Jackson deserializes to something other than LinkedHashMap.","commonSituations":"A client serializing the field incorrectly (e.g. a JSON number or array); passing a HashMap that Jackson maps to a different concrete type; malformed API payload from a generated SDK.","solutions":["Send workflowDefinition as a JSON object that deserializes to a WorkflowDef/LinkedHashMap.","Omit the field (null) when you only need the sub-workflow name.","Validate the payload type before submission - only object, string, or null are valid."],"exampleFix":"// before: scalar/array - rejected\n{\"subWorkflowParam\": {\"workflowDefinition\": 1}}\n\n// after: object form\n{\"subWorkflowParam\": {\"workflowDefinition\": {\"name\": \"myWorkflow\", \"version\": 1}}}","handlingStrategy":"type-guard","validationCode":"// Only allow object/string/null through to setWorkflowDefinition\nstatic boolean isAcceptableWorkflowDefinitionType(Object v) {\n    if (v == null) return true;\n    return v instanceof WorkflowDef || v instanceof LinkedHashMap || v instanceof String;\n}","typeGuard":"// Type-guard: accept only the supported runtime types\nstatic boolean isValidWorkflowDefinition(Object v) {\n    if (v == null) return true;\n    if (v instanceof WorkflowDef) return true;\n    if (v instanceof LinkedHashMap) return true;\n    return v instanceof String s && s.startsWith(\"${\") && s.endsWith(\"}\");\n}","tryCatchPattern":"// Catch the type error and reject the payload with context\ntry {\n    params.setWorkflowDefinition(raw);\n} catch (IllegalArgumentException e) {\n    throw new BadRequestException(\n        \"workflowDefinition has unsupported type: \" + raw.getClass(), e);\n}","preventionTips":["Send workflowDefinition as a JSON object, string, or omit it.","Validate the field type before submission.","Reject scalar/array payloads for workflowDefinition at the boundary."],"tags":["subworkflow","validation","type-mismatch","json","input"],"backgroundTag":null,"analyzedSha":"cf7c3e4a8adfb158be778ab1ec525323c363cd3a","analyzedAt":"2026-08-14T03:33:19.897Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}