windmill-labs/windmill · error

Invalid flow setting ${path}: ${issue?.message ?? 'unknown e

Error message

Invalid flow setting ${path}: ${issue?.message ?? 'unknown error'}

What it means

The flow's value settings (extra top-level settings carried alongside modules, e.g. timeout/retry-related keys covered by flowValueSettingsSchema) are parsed with zod; the first issue is rethrown as `Invalid flow setting <dotted-path>: <message>`. The dotted path pinpoints exactly which nested setting failed and why.

Source

Thrown at frontend/src/lib/components/copilot/chat/flow/editableFlowJson.ts:362

	// Reject unknown top-level keys: silently dropping them would make patch
	// tools report success for edits that never land on the flow.
	const allowedKeys = new Set<string>([
		...EDITABLE_FLOW_STRUCTURAL_KEYS,
		...FLOW_VALUE_SETTINGS_KEYS
	])
	const unknownKeys = Object.keys(flow).filter((key) => !allowedKeys.has(key))
	if (unknownKeys.length > 0) {
		throw new Error(
			`Unknown top-level flow key(s): ${unknownKeys.join(', ')}. Allowed keys: ${[...allowedKeys].join(', ')}`
		)
	}

	const settingsResult = flowValueSettingsSchema.safeParse(flow)
	if (!settingsResult.success) {
		const issue = settingsResult.error.issues[0]
		const path = issue?.path?.join('.') ?? 'settings'
		throw new Error(`Invalid flow setting ${path}: ${issue?.message ?? 'unknown error'}`)
	}
	const settings = pickFlowValueSettings(settingsResult.data)

	const modules = validateFlowModules(flow.modules, ctx)
	const schema = validateFlowSchema(flow.schema)
	const preprocessorModule = validateOptionalFlowModule(
		flow.preprocessor_module,
		'preprocessor_module'
	)
	const failureModule = validateOptionalFlowModule(flow.failure_module, 'failure_module')
	const groupModuleIds = new Set(collectAllFlowModuleIdsFromModules(modules))
	const groups = validateFlowGroups(flow.groups, groupModuleIds)
	const notes = validateFlowNotes(flow.notes, groupModuleIds)

	if (preprocessorModule) {
		if (preprocessorModule.id !== SPECIAL_MODULE_IDS.PREPROCESSOR) {
			throw new Error(
				`Invalid preprocessor_module: id must be "${SPECIAL_MODULE_IDS.PREPROCESSOR}"`

View on GitHub (pinned to e474e8803c)

Solutions

1. Read the dotted path in the message and correct that setting's type/value per flowValueSettingsSchema.
2. Use the exact keys and shapes listed in the error's 'Allowed keys' output from the unknown-key check.
3. Omit the setting entirely if the default is acceptable.

Example fix

// before
{"timeout":"30s"}
// after
{"timeout":30}

import { flowValueSettingsSchema } from './flowValueSettings'
const r = flowValueSettingsSchema.safeParse(flow)
if (!r.success) {
  for (const i of r.error.issues)
    console.error(`${i.path.join('.')}: ${i.message}`)
}

try {
  const editable = validateEditableFlowJson(raw)
} catch (e) {
  const m = /^Invalid flow setting (.+?): (.*)$/.exec(String(e.message))
  if (m) {
    // m[1] is the dotted settings path, m[2] the zod reason; fix and retry
  } else throw e
}

When it happens

Trigger: Calling flowTools parsedFlow/patch tools with a settings key present but with a wrong type or value — e.g. a string where a number is expected, or an invalid enum value at settings.priority.

Common situations: An LLM writes "timeout": "30s" where a number of seconds is required; a user copies a setting from an older flow format; an enum-like setting gets an out-of-vocabulary value.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Invalid ${field}:\n${errors.join('\n')}
• Flow modules must be an array
• Invalid flow modules:\n${errors.join('\n')}
• Invalid ${fieldName}: ${error?.message ?? 'unknown error'}
• ${label} is invalid: ${formatZodError(result.error)}

AI-assisted analysis of windmill-labs/windmill@e474e8803c (2026-09-03). Data as JSON: /api/errors/12bf00f4198b2de5. Report an issue: GitHub.