GitHub Actions needs context outputs are undefined

By Daniel Zoghalchali·Latchkey

A job's step output is not automatically visible to dependent jobs. The job must declare an outputs map that lifts the step output, and the dependent job must list it under needs. Miss either and needs.<job>.outputs.<name> is empty.

What this error means

A dependent job reads needs.<job>.outputs.<name> and gets an empty string, so a later step or condition misbehaves.

# build.outputs.version was never declared
echo "deploying ${{ needs.build.outputs.version }}"
-> deploying      (empty)

Common causes

Upstream job did not declare outputs

The producing job set a step output but never mapped it under jobs.<job>.outputs, so nothing crosses the job boundary.

Dependent job missing the needs edge

Without listing the upstream job in needs, its outputs context is unavailable.

How to fix it

Declare job outputs and the needs edge

1. In the producing job, map the step output to a job-level outputs entry.
2. In the consuming job, add the producing job to needs.
3. Reference needs.<job>.outputs.<name>; re-run.

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.meta.outputs.version }}
    steps:
      - id: meta
        run: echo "version=1.2.3" >> "${GITHUB_OUTPUT}"
  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: echo "deploy ${{ needs.build.outputs.version }}"

How to prevent it

• Lift step outputs to job-level outputs for anything dependent jobs need.
• List every producing job in the consumer's needs.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions