Unrecognized named-value CI/CD Origin: Build & delivery Last updated 25 Oct 2026

GitHub Actions: Unrecognized named-value: 'secrets'. Located at position 1 within expression: secrets.API_KEY

You used an expression context (secrets, env, matrix, steps…) in a place of the workflow where that context is not available.

Exact message you may see Unrecognized named-valueUnrecognized named-value: 'secrets'Unrecognized named-value: 'env'Unrecognized named-value: 'matrix'Located at position 1 within expression
Explore the map of this error Full error map →
Seen on: GitHub Actions

Meaning

Each workflow key allows only some contexts. secrets cannot be used in a job-level if:; env cannot be used in runs-on; steps is not available in jobs.<id>.if. Move the check into a step, use needs/outputs, or copy the value to an env first.

Common causes

  • secrets.* used in a job-level if:
  • env.* used in runs-on or uses
  • matrix.* used outside the job that defines the matrix
  • steps.* referenced from another job instead of needs.<job>.outputs
  • Typo in the context name (secret vs secrets)

⚡ Quick fix

  1. Check the "Context availability" table for that key in the docs
  2. Put the condition on a step, or expose the value via env: / outputs:
  3. Use needs.<job>.outputs.<name> to read values from another job

Detailed fix by platform

GitHub Actions

  1. Pass the secret to a step through env and test it there: env: HAS_KEY: ${{ secrets.API_KEY != '' }} then if: env.HAS_KEY == 'true' on a step

Code examples

Context availability

yaml
jobs:
  deploy:
    runs-on: ubuntu-latest
    # if: secrets.API_KEY != ''             # Unrecognized named-value: 'secrets'
    steps:
      - name: Deploy
        if: env.HAS_KEY == 'true'
        env:
          HAS_KEY: ${{ secrets.API_KEY != '' }}
        run: ./deploy.sh

How to diagnose

  1. Key — Which workflow key holds the expression?
  2. Context — Which context is named?
  3. Docs — Is it allowed there?

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

Where this error sits

Origin: Build & delivery. Errors that are often confused with or caused by this one (click to open):

API rate limit exceeded — GitHub Actions: HttpError: API rate limit exceeded for installation ID 123456 / secondary rate limit (CI/CD)API rate limit exceed…Cache not found / Unable to reserve cache — GitHub Actions: Cache not found for input keys: npm-Linux-abc123 / Failed to save: Unable to reserve cache with key, another job may be creating this cache (CI/CD)Cache not found / Una…Context access might be invalid — GitHub Actions: Context access might be invalid: AWS_ACCESS_KEY_ID (editor warning for secrets/vars) (CI/CD)Context access might …Credentials could not be loaded — GitHub Actions: Error: Credentials could not be loaded, please check your action inputs: Could not load credentials from any providers (CI/CD)Credentials could not…error parsing called workflow — GitHub Actions: error parsing called workflow ".github/workflows/ci.yml" -> "org/repo/.github/workflows/build.yml@main": workflow was not found (CI/CD)error parsing called …Invalid workflow file — GitHub Actions: Invalid workflow file: .github/workflows/ci.yml#L12 — You have an error in your yaml syntax on line 12 (CI/CD)Invalid workflow fileMatrix vector does not contain any values — GitHub Actions: Matrix vector 'node' does not contain any values / Error when evaluating 'strategy' for job (CI/CD)Matrix vector does no…Unable to download artifact — GitHub Actions: Error: Unable to download artifact(s): Artifact not found for name: build (CI/CD)Unable to download ar…Unrecogni…

Explore the map of this error Full error map →

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.

💬 What worked for others

No tips yet — did something else fix this for you?

Share what worked for you

Tips are checked by an editor before they appear. Links are removed.