What causes "Unknown Variable Access %s" in nektos/act?

Move the expression to a field that allows the context (job-level env, step env, step if)

Unknown Variable Access %s

Error message

Unknown Variable Access %s

What it means

Validation error from checkSingleExpression in pkg/schema/schema.go: the expression references a context variable (e.g. github, env, matrix) that is not in the current Node's Context list. Each schema node declares which top-level context variables are allowed; accessing anything else is rejected.

Source

Thrown at pkg/schema/schema.go:161

				if strings.EqualFold(funcCallNode.Callee, v.name) {
					if v.min > len(funcCallNode.Args) {
						err = errors.Join(err, fmt.Errorf("Missing parameters for %s expected >= %v got %v", funcCallNode.Callee, v.min, len(funcCallNode.Args)))
					}
					if v.max < len(funcCallNode.Args) {
						err = errors.Join(err, fmt.Errorf("Too many parameters for %s expected <= %v got %v", funcCallNode.Callee, v.max, len(funcCallNode.Args)))
					}
					return
				}
			}
			err = errors.Join(err, fmt.Errorf("Unknown Function Call %s", funcCallNode.Callee))
		}
		if varNode, ok := node.(*actionlint.VariableNode); entering && ok {
			for _, v := range s.Context {
				if strings.EqualFold(varNode.Name, v) {
					return
				}
			}
			err = errors.Join(err, fmt.Errorf("Unknown Variable Access %s", varNode.Name))
		}
	})
	return err
}

func (s *Node) GetFunctions() *[]FunctionInfo {
	funcs := &[]FunctionInfo{}
	AddFunction(funcs, "contains", 2, 2)
	AddFunction(funcs, "endsWith", 2, 2)
	AddFunction(funcs, "format", 1, 255)
	AddFunction(funcs, "join", 1, 2)
	AddFunction(funcs, "startsWith", 2, 2)
	AddFunction(funcs, "toJson", 1, 1)
	AddFunction(funcs, "fromJson", 1, 1)
	for _, v := range s.Context {
		i := strings.Index(v, "(")
		if i == -1 {
			continue

View on GitHub (pinned to 4f41128141)

Solutions

Move the expression to a field that allows the context (job-level env, step env, step if)
Pass the value through an env var from an allowed location: env: { TOKEN: ${{ secrets.MY_TOKEN }} }
Check the schema definition's Context array for the node to see which variables are permitted

Example fix

# before (context not allowed at this node):
run-name: deploy-${{ secrets.ENV_NAME }}
# after:
env:
  ENV_NAME: ${{ secrets.ENV_NAME }}
run-name: deploy-${{ env.ENV_NAME }}

Defensive patterns

Strategy: validation

Validate before calling

# Only reference context variables the node declares:
# allowed commonly: github, env, matrix (job), secrets (job/step), vars, inputs
# avoid secrets/vars in top-level fields like run-name or mapping keys

Try / catch

Validation failure — move the reference to a permitted field and re-validate.

Prevention

Pipe secrets through job/step env instead of structural fields
Check available contexts per field in the GitHub workflow docs
Validate workflows in CI with act's schema check

When it happens

Trigger: ${{ secrets.MY_TOKEN }} in a node whose Context only contains ['github', 'env'], or ${{ matrix.foo }} where matrix is not declared for that node (e.g. in a reusable-workflow-level field).

Common situations: Using secrets in places GitHub does not allow (e.g. run-name or keys without secrets context); referencing matrix/job/runner context in top-level workflow fields; assuming all contexts are available everywhere.

Related errors

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