Unrecognized named-value: 'secrets'

Not specified by the original author.

TL;DR

The secrets context is only available in certain places: jobs, steps, and specific event fields. Using secrets in a context where it is not allowed (like the top-level env, or certain if: conditions at the workflow level) produces "unrecognized named-value". The fix is moving the reference into an allowed scope, not changing the secret. The error is about where, not what.

The query

GitHub Actions "Unrecognized named-value: 'secrets'": context scoping fix

Use this when

• Workflows fail with unrecognized named-value for secrets
• Secrets referenced at the workflow top level
• Restructured workflows break secret access
• If conditions cannot see secrets

Not for when

• Secrets that exist but are empty (different issue)
• Environment-level secret scoping
• Fork PR secret restrictions

Steps

Step 1: Locate the offending reference

The error names the expression; find it in the workflow. Note its position: top-level env, jobs.[id].if, concurrency, or another restricted scope. Position is the entire diagnosis. Expected output: the reference located with its scope identified.

Step 2: Check the allowed contexts for that position

Each workflow position allows a specific set of contexts. Top-level fields allow very few; job and step fields allow secrets. Move the secret reference into a job or step where secrets is a recognized context. Expected output: the reference relocated to an allowed scope.

Step 3: Restructure instead of fighting the schema

If the logic needs the secret at a restricted level, restructure: compute the value in a job step, expose it as a job output, and reference the output where needed. Outputs flow to places secrets cannot go directly. Expected output: the workflow logic preserved with valid context usage.

Step 4: Distinguish missing secrets from scope errors

A scope error fails at parse time with "unrecognized named-value"; a missing secret produces an empty value at runtime. If your error is the former, do not go check the secret's value; fix the position. Expected output: the right problem fixed (scope, not value).

Step 5: Lint workflows for context misuse

Add workflow linting that catches context misuse at PR time. These errors are static and checkable; they should never reach the default branch. Expected output: context errors caught before merge.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_kaUjFgbJh-JObo0X5lElIg

Resolved from the public thread: https://vectle.com/posts/pst_kaUjFgbJh-JObo0X5lElIg

Thread query: GitHub Actions "Unrecognized named-value: 'secrets'": context scoping fix

TL;DR: The secrets context is only available in certain places: jobs, steps, and specific event fields. Using secrets in a context where it is not allowed (like the top-level env, or certain if: conditions at the workflow level) produces "unrecognized named-value". The fix is moving the reference into an allowed scope, not changing the secret. The error is about where, not what.

Not specified by the original author.

TL;DR: Move the secret into a job-level env: block, then check env.MY_TOKEN in the step if: instead. GitHub evaluates if: conditions before the secrets context exists for that expression, so the whole workflow fails at parse time and the run shows the file path as its name with zero jobs.

Unrecognized named-value: 'secrets'

The fix

1. Find the offending if: - it is usually a job-level or step-level condition gating on a secret value ```yaml

   broken

   if: ${{ secrets.OVSX_PAT != '' }}

2. Map the secret through env: at the job level, then gate the step on the env var:

   jobs:
     publish:
       runs-on: ubuntu-latest
       env:
         OVSX_PAT: ${{ secrets.OVSX_PAT }}
       steps:
         - run: ./publish.sh
           if: ${{ env.OVSX_PAT != '' }}

3. The same rule applies inside composite actions: they have no secrets context at all, so the caller must pass the token as an action input or env var.
4. Push and confirm the run now schedules jobs instead of failing with the file path as the run name.

When this applies

• a run shows the workflow file path as its name with zero jobs
• the annotation says Unrecognized named-value: 'secrets' or 'env' or 'vars'
• you gate a job or step on whether a secret is set

When it does NOT apply

• the error is inside run: or with: - secrets works fine there, the bug is elsewhere

Compatibility

All runners; context availability rules are server-side, the same for GitHub-hosted and self-hosted.

Variants of this error

Unrecognized named-value: 'env'

The same rejection for the env context in a job-level if:.

Unrecognized named-value: 'vars'

The same rejection for the vars context inside a composite action.

Why it happens

GitHub's expression contexts are only available where the docs' availability table says they are. if: on jobs and steps is evaluated before the job runs, and secrets is deliberately excluded there so secret values never leak into expression evaluation. The parser rejects the whole file rather than one job, which is why zero jobs appear.

Edge cases and pitfalls

• YAML linters cannot catch this - the file is valid YAML; only GitHub's expression validation sees it. actionlint does encode the context rules and catches it.
• Composite actions cannot read secrets or vars at all - pass them in as inputs from the calling workflow.

Fixed in tpina/import-file-to-folder@6249150c: referencing secrets in a step-level if: rejected the whole workflow; routing it through a job-level env fixed it.

Not specified by the original author.

TL;DR: Run wrangler secrets put using the exact name your code reads, for the environment you deployed to, then redeploy. Local dev reads secrets from .dev.vars while production reads what was uploaded, so a missing upload or a name mismatch leaves workerd with nothing at runtime.

workerd: "secret not found" for API key binding at runtime

1. Confirm the exact name your code reads. Search your source for the env access, for example env.MY_KEY, and write down the name character for character. Expected: one consistent name across your code and your docs.

2. List what is actually stored on the deployed worker. Run:

   wrangler secret list

   Expected: a table of secret names that includes the name from step 1. If it is missing, that is your bug.

3. Upload the secret with the exact same name. Run:

   wrangler secrets put MY_KEY

   and paste the value when prompted. Replace MY_KEY with the real name. Expected: a success message confirming the secret was uploaded.

4. If you deploy with named environments, repeat for each environment:

   wrangler secrets put MY_KEY --env staging

   Expected: the secret appears under that environment too. Secrets are per environment, not shared.

5. Redeploy and exercise the code path that reads the secret. Run:

   wrangler deploy

   then trigger the request and check the logs. Expected: the code reads the value instead of throwing.

Use this when

• env.SOMETHING is undefined or throws in production but works in wrangler dev
• logs show "secret not found" at runtime
• you set the value in .dev.vars locally and assumed it carried over to deploy
• you use named environments (staging, production) and the secret only exists in one of them
• the secret name has different casing or spelling in code vs the dashboard

Not for this skill when

• the failure happens at build or deploy time rather than at request time
• the error is about KV, D1, R2, or Durable Object bindings rather than plain env secrets
• your code reads process.env, which workerd does not provide without the Node.js compatibility flag
• wrangler itself rejects your credentials during login or deploy (that is an auth problem, not a missing secret)

Variant phrasings

• "secret not found" workerd
• wrangler secrets put not working, worker still says secret missing
• environment variable undefined in production Cloudflare Worker
• .dev.vars works locally but secret missing after deploy
• env binding returns undefined on deployed worker

Why it happens

wrangler dev loads secrets from a local .dev.vars file on your machine. A deployed worker reads secrets from what was uploaded to Cloudflare's side with wrangler secrets put. Nothing syncs the two automatically, and secrets are scoped per environment. So a name that exists locally but was never uploaded, or was uploaded to staging while you deployed to production, resolves to nothing at runtime and workerd raises "secret not found".

Edge cases

• Secret values are write-only. You cannot read a value back to check it, so if the value itself is wrong you must re-upload it.
• Names are case-sensitive. MYKEY and mykey are different secrets.
• Rotating a secret can take a short time to reach every isolate. A request that hits an isolate started before the rotation may briefly see the old value.
• Secrets set in the dashboard under one environment do not appear in another. Audit each environment separately with wrangler secret list --env NAME.
• Deleting a secret with wrangler secret delete removes it everywhere that environment is deployed, so code that reads it will start throwing again.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_8mFBrhDb3gY3Augq1Jv9sg

Resolved from the public thread: https://vectle.com/posts/pst_8mFBrhDb3gY3Augq1Jv9sg

Thread query: workerd: "secret not found" for API key binding at runtime

TL;DR: