Tool Node Input Validation#

Input validation for workflow tool nodes spans two layers: a frontend layer that classifies each parameter and renders the right control, and a backend layer that converts, type-checks, and resolves values before passing them to a tool. Understanding both layers is necessary when debugging unexpected validation failures or adding new parameter types.

Frontend: FormInputItem and helpers#

FormInputItem is the React component that renders a single tool parameter row in the workflow canvas. It drives all UI-side validation decisions.

State classification — getFormInputState() in form-input-item.helpers.ts derives a FormInputState object from the raw CredentialFormSchema and the current stored value. Key flags it computes:

Input kind — The three possible kinds are constant, variable, and mixed (from the VarKindType enum). Files are always variable kind; strings are always mixed; numbers, booleans, arrays, objects, dates, and date-ranges default to constant 2.

Variable filtering — getFilterVar() returns a per-type filter function used by VarReferencePicker to restrict which upstream variables can be selected. For example, a number input only accepts VarType.number; a file input accepts both VarType.file and VarType.arrayFile; a multi-select select or dynamic-select input accepts VarType.array and VarType.arrayString.

Variable clearing on type switch — handleTypeChange() in FormInputItem clears the current value when the user toggles between constant and variable kind: switching to variable sets value: ''; switching to constant resets to the schema's defaultValue.

Numeric inputs — FormInputItem uses Dify UI's NumberField component for numeric constant inputs. The component preserves the distinction between zero, decimal values, and empty/null states: a cleared input yields null rather than 0 or NaN. This provides precise control over numeric input validation and state management.

Placeholder disambiguation — Select dropdowns show the schema placeholder when no option is selected; for dynamic selects during loading, the trigger shows 'Loading...' instead of the placeholder 3.

Variable selector normalization — normalizeVariableSelectorValue() coerces falsy variable selector values (e.g., null, undefined) to '' before storing, preventing the picker from rendering stale references.

Variable type mapping — getTargetVarType() returns the VarType that a parameter expects when in variable mode. Multi-select select or dynamic-select parameters return VarType.arrayString, enabling variable pickers to only show compatible upstream array outputs.

Backend: _convert_tool_parameters_type() and _transform_tool_parameters_type()#

Runtime parameter resolution — _convert_tool_parameters_type() in api/core/tools/tool_manager.py iterates over all FORM-type ToolParameter objects and builds a runtime_parameters dict from workflow node inputs.

Three input modes (workflow context):

ToolNodeData.ToolInput (from the external graphon package) is validated via model_validate() before type dispatch.

Skipping unconfigured parameters — If config is missing or has no "value" key, the parameter is silently skipped (continue) 7. This is the mechanism that makes optional parameters truly optional at runtime.

Non-variable-pool (simple) path — Without a variable pool (e.g., direct app invocations), init_frontend_parameter() is called 8. When use_default_for_missing_form_parameters=True, a missing value falls back to parameter.default, then to the first option for SELECT types, then continue 9.

File parameters in agent mode — Required FILE, FILES, or SYSTEM_FILES parameters raise ValueError when called with typ="agent" and allow_file_parameters=False 10.

Type casting — After value extraction, cast_parameter_value() in api/core/plugin/entities/parameters.py coerces values to their declared types:

• NUMBER: accepts int/float directly; parses non-empty strings; empty strings return None via fallback 11
• FILE: unwraps single-item lists; raises if multiple files provided 12
• FILES / SYSTEM_FILES: wraps scalars into a list 13
• OBJECT: attempts json.loads() on strings before returning {} as fallback 14
• DATE: validates that the value is a string in YYYY-MM-DD format; empty strings return ''
• DATE_RANGE: accepts a dict or JSON string with optional start and end keys; validates both dates are in YYYY-MM-DD format and start ≤ end; empty values return {}

Multi-select normalization — _transform_tool_parameters_type() in api/core/tools/__base/tool.py normalizes tool parameter values before invocation. When parameter.multiple is True for SELECT or DYNAMIC_SELECT types, it calls parameter.init_frontend_parameter() to validate that the value is a list of strings. When parameter.multiple is False, it uses the original parameter.type.cast_value() behavior:

for parameter in self.entity.parameters or []:
    if parameter.name in tool_parameters:
        if parameter.multiple:
            result[parameter.name] = parameter.init_frontend_parameter(result.get(parameter.name))
        else:
            result[parameter.name] = parameter.type.cast_value(tool_parameters[parameter.name])

Tool parameter validation (ToolParameter)#

Multi-select declaration — ToolParameter includes a multiple boolean field (default: False) that enables multi-select behavior for SELECT and DYNAMIC_SELECT parameter types. When multiple=True, the parameter accepts an array of strings instead of a single value [validate_multiple()]:

• The multiple field is only valid for SELECT and DYNAMIC_SELECT parameter types; using it on other types raises a ValueError.
• When multiple=True, the default value must be a list; otherwise a ValueError is raised.
• When multiple=False, the default value must not be a list.

Multi-select runtime validation — When parameter.multiple=True, init_frontend_parameter() enforces:

• The value must be a list of strings (raises ValueError if not).
• Required parameters reject empty lists (raises ValueError with message "tool parameter {name} not found in tool config").
• For SELECT types, all list items must be valid options (raises ValueError if not).
• If value is None, it defaults to parameter.default or [].

LLM schema generation — get_llm_parameters_json_schema() generates different JSON schemas for multi-select parameters:

When multiple=True for SELECT or DYNAMIC_SELECT:

{
  "type": "array",
  "items": {
    "type": "string",
    "enum": ["option1", "option2"]
  }
}

When multiple=False:

{
  "type": "string",
  "enum": ["option1", "option2"]
}

Application-level file input validation (BaseAppGenerator)#

For workflow/chat app inputs (not tool parameters), _validate_inputs() in api/core/app/apps/base_app_generator.py applies an additional layer:

• Optional file placeholder fix (PR #28948): If a FILE or FILE_LIST variable is optional and its value is an empty string (the frontend default), the method returns None rather than failing type validation 15. This prevents the frontend's universal default: '' from causing false validation failures.
• Number empty string — An empty or whitespace-only string for a NUMBER variable returns None instead of raising 16.
• Required guard — If value is None and variable_entity.required, a ValueError is raised immediately before any type-specific checks 17.

Key source files#

Related PRs:

• PR #39346: Add multi-select support for tool SELECT and DYNAMIC_SELECT parameters
• PR #28948: Fix optional file input empty-string placeholder validation
• PR #22903: Refine constant/mixed input handling in ToolManager and ToolNodeData; tighten check_type() to allow dicts as constant values