windmill-labs/windmill · error · Error

${errorMessage}

Error message

${errorMessage}

What it means

utils/OpenApi.parse validates an OpenAPI document (JSON or YAML string) with @scalar/openapi-parser before dereferencing. If validate() reports valid=false, it throws an Error whose message is all validation error messages joined by newlines, or 'Invalid OpenAPI document' when no detailed errors are returned.

Source

Thrown at frontend/src/lib/utils.ts:68

	/**
	 * Parses and validates an OpenAPI specification provided as a string in either JSON or YAML format.
	 *
	 * @param api - A string containing a valid OpenAPI specification in JSON or YAML format.
	 * @returns A promise that resolves to a tuple:
	 *   - The first element is the validated OpenAPI document.
	 *   - The second element is the detected OpenAPI version (2, 3.0, or 3.1).
	 *
	 * @throws Will throw an error if the specification is invalid or cannot be parsed.
	 */
	export async function parse(api: string): Promise<[OpenAPI.Document, OpenApiVersion]> {
		const { validate, dereference } = await import('@scalar/openapi-parser')
		const { valid, errors } = await validate(api)

		if (!valid) {
			const errorMessage = errors
				? errors.map((error) => error.message).join('\n')
				: 'Invalid OpenAPI document'
			throw new Error(errorMessage)
		}

		const document = await dereference(api)

		const version = getOpenApiVersion(document.version!)

		return [document.schema, version]
	}
}

export function isJobCancelable(j: Job): boolean {
	return j.type === 'QueuedJob' && !j.schedule_path && !j.canceled
}

export function isJobReRunnable(j: Job): boolean {
	return (j.job_kind === 'script' || j.job_kind === 'flow') && j.parent_job === undefined
}

View on GitHub (pinned to e474e8803c)

Solutions

1. Read the thrown message — it lists each validation error from @scalar/openapi-parser; fix the referenced paths/fields
2. Validate the spec locally with a linter (e.g. Redocly CLI or swagger-editor) to pinpoint issues
3. Ensure required fields (openapi, info.title, info.version, paths) exist and $refs resolve
4. Convert Swagger 2.0 documents to OpenAPI 3 before importing

Example fix

// before
const [doc, version] = await OpenApi.parse(userSpec) // throws joined validation errors
// after
let doc, version
try {
  ;[doc, version] = await OpenApi.parse(userSpec)
} catch (e) {
  console.error('OpenAPI validation failed:', e.message) // per-line validation errors
  showSpecError(e.message)
}

// lightweight pre-checks before OpenApi.parse
function looksLikeOpenApiSpec(api: string): boolean {
  return /"openapi"\s*:|^openapi:\s*['"]?3/im.test(api)
}
if (!api.trim() || !looksLikeOpenApiSpec(api)) {
  throw new Error('Not an OpenAPI 3.x document (got Swagger 2.0 or invalid input?)')
}

function isOpenApiValidationMessage(err: unknown): err is Error & { message: string } {
  return err instanceof Error && (err.message.includes('Invalid OpenAPI') || /invalid|must|required/i.test(err.message))
}

try {
  const [doc, version] = await OpenApi.parse(api)
} catch (err) {
  if (err instanceof Error) {
    // message contains one validation error per line — show all to the user
    showValidationErrors(err.message.split('\n'))
    return
  }
  throw err
}

When it happens

Trigger: Calling parse() with a spec that fails schema validation: missing required 'openapi'/'info'/'paths' fields, wrong types, invalid references, or unparseable YAML/JSON; also OpenAPI 2.0/Swagger docs that violate 3.x rules the parser enforces.

Common situations: Pasting a Swagger 2.0 spec into an OpenAPI 3 importer; hand-edited specs with broken $refs; truncated or YAML-indentation-broken documents; specs served with wrong content generating invalid JSON.

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 flow modules:\n${errors.join('\n')}
• Invalid failure_module: only "rawscript" and "script" module
• Invalid note at index ${index}: position must be an object w
• Invalid note at index ${index}: size must be an object with
• Invalid note at index ${index}: contained_node_ids must be a

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