Kay

Posted on Nov 15 Originally published at latchkey.dev

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

#githubactions #devops #cicd #debugging

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.

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.

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.

```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




## Common causes

### 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.

## 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

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.

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




## 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 is | Contexts that key accepts | Result |
| --- | --- | --- |
| `action.yml`, an input `default` | `github, strategy, matrix, job, runner`, `hashFiles` | rejected |
| `action.yml`, unknown top-level keys such as `on` or `jobs` | none | rejected |
| `on.workflow_dispatch.inputs.<id>.default` | none | rejected |
| `uses:` on a step or a reusable workflow call | none | rejected |
| `action.yml`, a step `run`, `with`, `env` or `if` | includes `inputs` | accepted |
| any workflow key that takes an expression | includes `inputs` | accepted, empty when nothing was passed |

> The action rows are read from `src/Runner.Worker/action_yaml.json` and the workflow rows from `src/Sdk/WorkflowParser/workflow-v1.0.json` in actions/runner, read 2026-11-12, together with the context availability table on docs.github.com.

## 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.

The same message with a different name in quotes is the same class of problem: GitHub Actions unrecognized named-value.

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.

FAQ

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.

DEV Community