GitHub Actions Composite Action "Unexpected input" / Input Not Found

By Daniel Zoghalchali·Latchkey

A composite action fails because an input is not declared in its action.yml, a run step is missing the required shell:, or inputs are referenced with the wrong syntax inside the action.

What this error means

Calling a local composite action warns "Unexpected input(s)", or the action fails to load with "Required property is missing: shell", or inputs read as empty inside the action.

Warning: Unexpected input(s) 'verison', valid inputs are ['version']
# or
Error: Required property is missing: shell

Common causes

Input not declared in action.yml

Composite actions only accept inputs listed under inputs:. Passing an undeclared (or misspelled) input warns and the value is unavailable.

Missing shell on a composite run step

Every run step in a composite action must specify shell:. Omitting it fails the action at load time.

How to fix it

Declare inputs and set shell

List each input under inputs: and give every composite run step an explicit shell.

# action.yml
inputs:
  version:
    required: true
runs:
  using: composite
  steps:
    - run: echo "v=${{ inputs.version }}"
      shell: bash

Reference inputs correctly inside the action

1. Use ${{ inputs.<name> }} inside the composite action, not env or matrix.
2. Match the input name exactly between the caller with: block and action.yml.
3. Use default: in action.yml for optional inputs.

How to prevent it

• Declare every input in action.yml and document required ones.
• Always set shell: on composite run steps.
• Validate composite action.yml files with actionlint.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions