Actions YAML Schema Validation Error detected:\nFor more inf

Error message

Actions YAML Schema Validation Error detected:\nFor more information, see: https://nektosact.com/usage/schema.html

What it means

Workflow.UnmarshalYAML first validates the raw YAML node against act's JSON schema (definition workflow-root) before decoding. On validation failure it joins the schema error(s) with this hint pointing at the schema documentation. The underlying schema errors in the joined chain identify the exact failing node paths.

Source

Thrown at pkg/model/workflow.go:81

		if !decodeNode(w.RawOn, &val) {
			return nil
		}
		return val[event]
	}
	return nil
}

func (w *Workflow) UnmarshalYAML(node *yaml.Node) error {
	// Resolve yaml anchor aliases first
	if err := resolveAliases(node); err != nil {
		return err
	}
	// Validate the schema before deserializing it into our model
	if err := (&schema.Node{
		Definition: "workflow-root",
		Schema:     schema.GetWorkflowSchema(),
	}).UnmarshalYAML(node); err != nil {
		return errors.Join(err, fmt.Errorf("Actions YAML Schema Validation Error detected:\nFor more information, see: https://nektosact.com/usage/schema.html"))
	}
	type WorkflowDefault Workflow
	return node.Decode((*WorkflowDefault)(w))
}

type WorkflowStrict Workflow

func (w *WorkflowStrict) UnmarshalYAML(node *yaml.Node) error {
	// Resolve yaml anchor aliases first
	if err := resolveAliases(node); err != nil {
		return err
	}
	// Validate the schema before deserializing it into our model
	if err := (&schema.Node{
		Definition: "workflow-root-strict",
		Schema:     schema.GetWorkflowSchema(),
	}).UnmarshalYAML(node); err != nil {
		return errors.Join(err, fmt.Errorf("Actions YAML Strict Schema Validation Error detected:\nFor more information, see: https://nektosact.com/usage/schema.html"))

View on GitHub (pinned to 4f41128141)

Solutions

Unwrap errors.Join output to see each schema violation and its path.
Fix each flagged key per https://nektosact.com/usage/schema.html.
If the key is genuinely valid on GitHub but rejected by act's schema, report it upstream and temporarily remove the key locally.

Example fix

# before
on:
  push
jobs: {}
# after
on:
  push: {}
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: echo ok

Defensive patterns

Strategy: validation

Validate before calling

// quick structural pre-check before handing a file to act
var probe map[string]interface{}
if err := yaml.Unmarshal(raw, &probe); err != nil { return err }
if _, ok := probe["jobs"]; !ok { return fmt.Errorf("workflow missing 'jobs' key") }

Try / catch

if err != nil {
    var joined interface{ Unwrap() []error }
    if errors.As(err, &joined) {
        for _, e := range joined.Unwrap() { log.Error(e) } // per-node schema errors
    }
}

Prevention

Validate workflows against the published act/GitHub JSON schema in your editor.
Run act plan-only (`act -n`) in CI to catch schema issues early.
Treat unknown-key warnings from actionlint as fix-now, not later.

When it happens

Trigger: Any workflow whose top-level structure violates the schema: unknown root keys, wrong types (e.g. `on:` as a non-mapping when a mapping is required), invalid job structure, or bad step shape.

Common situations: Workflows using GitHub features act's vendored schema does not know; typos at top level (`job:` instead of `jobs:`); tool-generated YAML with unexpected wrapper keys.

Related errors

AI-assisted analysis of nektos/act@4f41128141 (2026-08-15). Data as JSON: /api/errors/cc7ab4014569ca76. Report an issue: GitHub.