Skip to content
Latchkey LogoLatchkey home

GitHub Actions unrecognized named-value: inputs, and the context that is missing

GitHub Actions unrecognized named-value: inputs means the expression sits in a key whose allowed contexts leave inputs out: an input default in action.yml, a workflow_dispatch input default, a uses: line, or workflow keys pasted into an action. Every expression key in a workflow accepts inputs, so a file with no declared input reads an empty string rather than failing; the fix is to move the reference into a step, env or with, where the context is offered.

Annotation, quoted from nicholaslee119/claude-code-github-action#1
nicholaslee119/claude-code-github-action/0.1.0/action.yml (Line: 49, Col: 14):
Unrecognized named-value: 'inputs'. Located at position 1 within expression: inputs.issue-number

01Symptom

What this error means

The workflow or the action fails before anything runs. The message names inputs as the unrecognized name, gives a file, a line and a column, and prints the expression back, so it reads like a spelling mistake even though the name is right. The detail that gives it away is the file in the message. In most reports it is an action.yml, often one you did not write, because an action is parsed against its own schema and some of its keys are offered very few contexts. A workflow triggered only by push that reads inputs.environment is not rejected at all: the value is simply empty. When the message does name a workflow file, look at the key rather than the trigger, because a workflow_dispatch input default and a uses: line take no contexts, so any name in an expression there is unrecognized.

A minimal action that produces it

This file is written for this page and has never been run. It is the shape from nicholaslee119/claude-code-github-action#1, reduced: an action whose second input builds its default from the first. The YAML is valid, the expression is well formed and the name exists. An input default in action.yml is simply offered github, strategy, matrix, job and runner plus the hashFiles function, and inputs is not on that list.

action.yml (illustrative)
name: open-branch
description: Create a working branch for an issue
inputs:
  issue-number:
    required: true
  branch-name:
    default: 'fix/issue-${{ inputs.issue-number }}'
runs:
  using: composite
  steps:
    - run: git switch -c "${{ inputs.branch-name }}"
      shell: bash

02Cause

Common causes

Workflow keys and action steps accept inputs, while an action input default rejects the name
Every expression key in a workflow accepts inputs and reads an empty string when nothing was passed. The rejections come from action input defaults, dispatch defaults and uses: lines.

An action input default reads another input

The case in the annotation at the top. An input default in action.yml is evaluated before the action has inputs to read, so its context list is github, strategy, matrix, job and runner only. A default built from a sibling input is rejected the moment any workflow loads the action, which is why the report usually comes from a consumer.

A workflow was pasted into action.yml

actions/runner#3307 is this shape: a file with workflow_dispatch and workflow_call blocks and a jobs map, called with uses: ./.github/actions/dev. The action schema has no on or jobs keys. It tolerates unknown top-level keys as loose values with no contexts, so the first expression inside them is rejected.

The expression is in a key that takes no contexts

A workflow_dispatch input default must be a literal, and a uses: line, on a step or on a reusable workflow call, cannot be computed at all. The schema gives both an empty context list, so every name in an expression there is unknown. BeirutOrg/checkout#19 shows the same failure in a dispatch default, with vars quoted instead of inputs. The parser checks names first, so an expression there that names no context at all, like ${{ true && '' || 'job2' }} in needs: in community discussion #38492, is refused with "A template expression is not allowed in this context" instead.

Not a cause: a workflow that declares no input

A file triggered by push or schedule that reads inputs.environment is accepted, and the value is an empty string. If that is your situation the symptom is a step running with a blank argument, not this message, and the fix is a fallback with || or a declared workflow_dispatch input.

03Fix

How to fix it

Read the file and the key in the message first

  1. If the path is an action.yml, check whether the line is under inputs (a default) or at the top level (workflow keys pasted into an action).
  2. If the path is a workflow, check whether the line is a workflow_dispatch input default or a uses: line.
  3. Move the reference to a key whose context list includes inputs: a step run, env, with or if.

Compute the fallback in the step, not in the metadata

Leave the input default empty and resolve the fallback where it is used. A step's env in an action is offered inputs, and format plus || covers the case where the caller passed nothing.

action.yml (illustrative)
    - run: git switch -c "$BRANCH"
      shell: bash
      env:
        BRANCH: ${{ inputs.branch-name || format('fix/issue-{0}', inputs.issue-number) }}

Turn a workflow-shaped action into a composite action

An action reads its inputs from an inputs: map beside name and runs, and a composite action reaches them through the same inputs context. There is no on: key and no jobs: map in an action. If what you have really is a workflow, keep it under .github/workflows/ and call it from a job with uses: instead.

.github/actions/deploy/action.yml (illustrative)
name: deploy
inputs:
  environment:
    description: target environment
    required: true
runs:
  using: composite
  steps:
    - run: ./deploy.sh "${{ inputs.environment }}"
      shell: bash

Choose a reference with if rather than computing uses

A uses: value is fixed when the file is read. Write one calling job per reference and let a job-level condition, which accepts inputs, decide which one runs.

.github/workflows/release.yml (illustrative)
jobs:
  deploy-stable:
    if: inputs.channel == 'stable'
    uses: ./.github/workflows/deploy.yml
  deploy-canary:
    if: inputs.channel == 'canary'
    uses: ./.github/workflows/deploy-canary.yml

Where the inputs context exists

The contexts reference defines it as the context that "contains input properties passed to an action, to a reusable workflow, or to a manually triggered workflow". Whether a name is allowed is decided per key, not per trigger. The context availability table lists inputs for every workflow key that takes an expression, from run-name and concurrency down to jobs.<job_id>.steps.run, and the workflow schema published in actions/runner agrees: no key in it has a context list that leaves inputs out.

So in a workflow file the parser never rejects the name. What the trigger decides is the value. workflow_call fills it from the caller's with:, workflow_dispatch fills it from the run form, and on any other event a property of it reads as an empty string, because dereferencing a property that is not there "will evaluate to an empty string". That is what makes ${{ inputs.target || 'staging' }} work in a file triggered by both push and workflow_dispatch.

The keys that do refuse it are few, and every report of this message we found is one of the rows below.

Where the expression isContexts that key acceptsResult
action.yml, an input defaultgithub, strategy, matrix, job, runner, hashFilesrejected
action.yml, unknown top-level keys such as on or jobsnonerejected
on.workflow_dispatch.inputs.<id>.defaultnonerejected
uses: on a step or a reusable workflow callnonerejected
action.yml, a step run, with, env or ifincludes inputsaccepted
any workflow key that takes an expressionincludes inputsaccepted, empty when nothing was passed

Move the reference to a key that accepts it

The fix is to move the expression, not to add a declaration. For an action input default, leave the default empty and build the fallback in the step that uses it, where inputs is offered. The || operator returns its right-hand side when the left is empty, so the caller's value wins when there is one and the computed name is used when there is not.

The same move works for a workflow_dispatch default, which must be a literal: leave it empty and resolve the fallback inside the job. For a uses: line, which can never hold an expression, write one job per reference and choose between them with a job-level if, which does accept inputs.

action.yml, corrected (illustrative)
name: open-branch
description: Create a working branch for an issue
inputs:
  issue-number:
    required: true
  branch-name:
    description: Defaults to fix/issue-<issue-number>
    required: false
runs:
  using: composite
  steps:
    - run: git switch -c "$BRANCH"
      shell: bash
      env:
        BRANCH: ${{ inputs.branch-name || format('fix/issue-{0}', inputs.issue-number) }}

The other place values arrive from

When a value comes in on an event payload rather than through a declared input, it is not in this context and never will be. A repository_dispatch carries a client payload, a workflow_run carries the run that triggered it, and both are read through the github context. The manual trigger is the one case where both work, because a dispatch input is written into the event payload as well, which is why older workflows read github.event.inputs and newer ones read inputs.

Prefer the declared context when you have the choice. It is typed, and it is populated the same way whether the run was called or dispatched, so one expression covers both paths.

Why there is no recorded run on this page

The parser rejects the file before a job exists, so there is no log from a runner to record and nothing transient for a runner to repair. The annotation quoted above comes from a public issue and names an action.yml, because an action's metadata is checked by the same expression parser against its own schema. actions/runner#3307 reports the identical line, Unrecognized named-value: 'inputs', from a workflow-shaped file used as a local action.

04Prevent

How to prevent it

  • Keep input defaults in action.yml and in workflow_dispatch literal, and compute fallbacks in the steps.
  • Never put an expression in a uses: line; choose between fixed references with if.
  • Keep composite action metadata separate from workflow files: no on: key, no jobs: map, inputs at the top level.
  • Lint actions as well as workflows, with a tool that knows the per-key context lists of both schemas.

Frequently asked questions

Why is the inputs context not recognized in my workflow?
In a workflow file it is accepted in every key that takes an expression, so the message almost always points at a key that takes none, a workflow_dispatch input default or a uses: line, or at an action.yml. A workflow triggered by push that reads inputs gets an empty string, not this error.
What is the difference between inputs and github.event.inputs?
The first is a declared, typed context created by workflow_call or workflow_dispatch. The second is a field on the event payload, which only exists for a manual run. A dispatch input appears in both, which is why both forms are seen in the wild; a reusable workflow input appears only in the declared context.
Can an action input default use another input?
No. The action schema offers an input default github, strategy, matrix, job and runner plus hashFiles, so ${{ inputs.x }} there is rejected. Leave the default empty and compute the fallback in the step with ||, where the inputs context is available.
Which triggers populate the inputs context?
Two: workflow_call, where the names and types come from the called workflow and the values from jobs.<job_id>.with in the caller, and workflow_dispatch, where they come from the manual run form. On every other event the context is empty and its properties read as empty strings, so read event data through the github context instead.

References

One runs-on line in a reusable workflow moves every caller onto Latchkey. Start free → 30-day trial · No credit card