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

Diagnose it: print the context before you change anything

Most workflow-expression bugs are not syntax errors, they are an expression reading something that is empty. GitHub resolves a missing property to an empty string instead of failing the run, so a wrong reference looks like a logic bug rather than a mistake. Dump the contexts first and you will usually see the answer immediately.

- name: Dump contexts
  run: |
    echo '--- github ---'   ; echo '${{ toJSON(github) }}'
    echo '--- needs ---'    ; echo '${{ toJSON(needs) }}'
    echo '--- steps ---'    ; echo '${{ toJSON(steps) }}'
    echo '--- matrix ---'   ; echo '${{ toJSON(matrix) }}'
    echo '--- inputs ---'   ; echo '${{ toJSON(inputs) }}'

Check the context is allowed where you used it

Contexts are not available everywhere. The same expression can be valid in a step if and invalid in a job if, which is why an expression that works in one workflow fails when moved.

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.

Catch it before it reaches CI

Every failure in this cluster is statically detectable. actionlint parses workflow expressions, checks context availability against the same rules above, and validates needs references, so these bugs never need to cost you a run.

# one-off
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color

# as a job, before anything expensive runs
- uses: actions/checkout@v4
- run: |
    bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
    ./actionlint -color

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