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

**Code:** `Unrecognized named-value` · **Category:** CI/CD · **Seen on:** GitHub Actions

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

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

---
Source: [WhatIsMyError](https://whatismyerror.com/errors/cicd/gha-unrecognized-named-value)