---
title: Secrets
description: Fix code that finds no stored secret, a deploy refused for a missing secret, a refused secret or provision line, or a local run reading a stale shell variable.
slug: /troubleshooting/secrets
order: 3
visibility: public
redirects_from: []
---

# Secrets

These entries start from what your code or a refusal shows about a value you stored. [Store a secret](/cloud/getting-started/store-a-secret/) describes the two ways a stored value reaches your application.

## Code reads a stored secret from process.env and finds nothing

**Cause.** Storing a value does not by itself make it an environment variable. A [declared upstream](/cloud/concepts/glossary/#declared-upstream)'s key stays at the [egress gateway](/cloud/concepts/glossary/#egress-gateway), which adds it to each call your code makes to that upstream through the gateway. A value reaches your code as a [setting](/cloud/concepts/glossary/#setting) only where the [manifest](/cloud/concepts/glossary/#manifest)'s `settings` member binds its name, and only from the environment's next deploy or promote.

**Check.** `list_secrets` shows a row for the name. Its `settings` member lists the settings the manifest binds to the name, and is empty where the manifest binds none. The row's `applied_settings` lists the settings the running copy of your application reads from the name. A setting missing there reaches the running copy at the next deploy or promote. `list_outbound_apis` returns each upstream's `credential_name`, which shows whether an upstream uses the name as its key.

A local run's environment file contains the settings listed in [Run your app on your computer, step 2 (Read the settings the file holds)](/cloud/guides/run-your-application-on-your-machine/#2-read-the-settings-the-file-holds). It contains no setting bound to a stored secret.

**Remedy.** For the key of an external application programming interface (API), declare the upstream first ([Declare the upstream](/cloud/guides/call-an-external-api-with-an-api-key/#2-declare-the-upstream)), then call the API through the gateway. A call to an upstream name not declared is refused 404 `undeclared_upstream`. For an unchanged software development kit (SDK), declare the upstream with `sdk_settings` instead, so the SDK reads its base URL and an [egress key](/cloud/concepts/glossary/#egress-key) ([An unchanged SDK](/cloud/guides/call-an-external-api-with-an-api-key/#an-unchanged-sdk)). For a value your code must read itself, bind it as [Bind a value to a setting](/cloud/getting-started/store-a-secret/#bind-a-value-to-a-setting) shows. Store it at each environment's scope of the application, submit the manifest, and deploy again.

## A deploy or promote is refused `setting_secret_missing`

**Cause.** The manifest's `settings` binds a setting to a stored name, and the environment being deployed has no value under that name at its own scope. Each environment reads only its own scope, so a value stored for development is unavailable in production, and the other way round. `store_secret` stores at production unless the call gives `environment` `development`.

**Check.** The response has status 409, and its `error` is `setting_secret_missing`. The `detail` gives the setting and the stored name, and its `next` gives the `store_secret` call to make. `list_secrets` with the application and the environment shows no row for that name. A `submit_manifest` response's `settings` rows show, per setting and environment, whether the name is stored there, and its `next` lists the `store_secret` call to make.

**Remedy.** Store the value with `store_secret`, giving the application, the environment the deploy goes to, and the name the `detail` gives, then deploy or promote again. The refusal's `next` is that call, filled in. Or, where the code no longer reads the setting, remove the binding from the manifest's `settings`, submit the manifest, and deploy again. [Store a secret](/cloud/getting-started/store-a-secret/#1-choose-the-name-and-the-scope) explains the scopes.

## The running copy seems to use the old value after a rotation

**Cause.** Rotating a secret changes the value the platform stores. A bound setting reaches the running copy only when a new copy starts: at the next deploy or promote, or at a `restart_application` where the copy already has the binding. A restart made while a deploy is still in progress is refused. A restart that fails its health check leaves the old copy running.

**Check.** `list_secrets` with the application and the environment shows the name's row. Its `fingerprint` is a short fingerprint the platform makes from the stored value with a key of its own. `applied_fingerprint` is the matching fingerprint for the value the running copy received when it last started. Neither fingerprint is the value or a hash of it, and neither can be tested offline. Only someone allowed to overwrite the live secret could compare a guess. Where the two fingerprints are equal, the running copy has the stored value. Where they differ, it still has the previous one.

The first four characters of a fingerprint are the id of the key that made it. Two fingerprints can be compared only where those four characters agree. A null fingerprint means none was recorded on that side: the value was stored, or the copy started, before the platform made fingerprints, or the platform did not yet hold its key. `read_status` lists each name whose two fingerprints differ in the environment's `settings_mismatch`. Its `settings_apply` names the action that gives the running copy the stored value.

**Remedy.** Call `restart_application` for that environment. Wait with `read_status` and `wait_seconds` until the restart's row ends `deployed`. Then read `list_secrets` again: the two fingerprints now agree, and `settings_mismatch` is empty. If `settings_mismatch` reads `not_comparable`, the platform's key changed between the two fingerprints. A restart records a fingerprint under the current key and clears the entry. A deploy or promote, if you want one anyway, also starts a new copy and clears it.

## A partner's signatures never verify

**Cause.** The secret your code checks signatures with was created with `store_secret`'s `generate`, but the sender issued the value. The platform never returns a created value, so the sender and your code hold different values.

**Check.** `list_secrets` lists the name at the scope of the environment that receives the calls. Then check how the value was stored: a call that named `generate` returned `generated` and no command line, so the value it stored is not the sender's.

**Remedy.** Save the sender's value in a file outside your application's folder. Store it under the same name with `value_file`: call `store_secret` with `replace: true` where the name is already stored, or without `replace` where it is not. Bind the name to the setting your code reads in the manifest's `settings`, as [Receive a signed webhook](/cloud/guides/receive-a-signed-webhook/) shows. A running copy that already has the binding reads the new value after the `restart_application` call the rotation's `next` gives.

## The secret line is refused `authentication_required` and says the grant was not accepted

**Cause.** The command that `store_secret` returned presented a [secret grant](/cloud/concepts/glossary/#secret-grant) the platform no longer has. The grant expired and was removed, or the command was changed, for example cut short when it was copied.

**Check.** The command printed a refusal with HTTP status 401 and `authentication_required`, and its explanation opens "The grant this request presented was not accepted". Nothing was written.

**Remedy.** Ask your AI tool to call `store_secret` again for a fresh command. Leave `value` out and keep `replace: true` for a replacement. Run the command whole, as given, before its `expires_at`. Signing in again does not help, because the refusal is about the command's secret grant. [Keep a secret value out of chat](/cloud/guides/supply-a-secret-value-without-exposing-it/#refusals) lists each refusal of the command.

## The secret line is refused `secret_grant_expired`

**Cause.** The command ran after the `expires_at` its call returned. A grant lasts fifteen minutes, so a command that waits for you to type a value can run out of time.

**Check.** The command printed a refusal with status 403 and the `error` `secret_grant_expired`. Nothing was written, and a stored value is unchanged.

**Remedy.** Ask your AI tool to call `store_secret` again for a fresh command. Leave `value` out and keep `replace: true` for a replacement. Run the command before its `expires_at`. If you type the value yourself, have it ready before your tool makes the call.

## The secret line is refused `secret_grant_spent`

**Cause.** The command presented a secret grant that was used earlier, so it wrote nothing. A grant permits one write only. Most often the same command ran twice, and its first run stored the value.

**Check.** The command printed a refusal with status 403 and the `error` `secret_grant_spent`. `list_secrets` shows when the name was last written, in `created_at` or `rotated_at`.

**Remedy.** Do not run the same command again. If its first run ended with status 0, the value is stored. If the command's first run was refused, or `list_secrets` shows no write at the time it first ran, another party used the same secret grant, and the stored value may be theirs. Store or rotate a value of your own at once, and treat the command as exposed. Ask your AI tool to call `store_secret` again for a fresh command. Leave `value` out and keep `replace: true` for a replacement. Run the command to replace what is stored under the name.

## The secret line is refused `secret_grant_not_admitted`

**Cause.** A grant is for one write: the action, the name, the application, and the environment of the call that returned the command. The command was changed, for example to another `--name`, or it was used for something else, such as a restart.

**Check.** The command printed a refusal with status 403 and the `error` `secret_grant_not_admitted`. Nothing was written, and the grant is not spent.

**Remedy.** Run the command exactly as the call returned it, before its `expires_at`. For another name or scope, ask your AI tool to call `store_secret` again for that name and scope. Leave `value` out and keep `replace: true` for a replacement. Run the command it returns.

## The provision line is refused

**Cause.** The provision line uses a [secret grant](/cloud/concepts/glossary/#secret-grant) to replace the local run's platform credential, and its database credential if the manifest declares a database, once within fifteen minutes. The old values then stop working. A verifier is a random secret the command keeps on this computer. The platform checks it against the challenge the command printed earlier.

`secret_grant_spent` means an earlier run of the command already used its grant, or someone who read this computer's credential file used it first. `secret_grant_expired` means the command ran after its `expires_at`. `authentication_required` means the platform found no grant matching this computer's verifier and the requested application. The command was changed, for example to give another `--application`, or ran on another computer.

**Check.** If the first request was refused, the command's message included "pending verifier" and "nothing was re-minted". That means no grant matched this computer's saved verifier and no credential was replaced. It named the refusal and printed the challenge and call again. The environment file is as it was. Where the refusal came on the second request, the command ended with status 2. It printed "The development database credential was re-minted and its value was not written".

**Remedy.** Run `turnzero provision --application <application id>` with nothing piped, and make any call it prints, then run the command that call returns as given. That command re-mints the platform credential, and the database credential where your manifest declares one, so a value someone else received stops working. If a response to a request that named `local_run` has no `provisioning`, the platform could not prepare the command; run `turnzero provision --application <application id>` with nothing piped, and make any call it prints.

## A local run is refused or reaches the wrong application though .env is current

**Cause.** `node --env-file=.env` keeps a variable already set in your shell and ignores the file's line for it. With the `run` line the file wins over the shell, so this happens only where the run was started with `node --env-file`, as the one-command check in [Run your app on your computer](/cloud/guides/run-your-application-on-your-machine/#check-the-run-in-one-command) does. A `TURNZERO_CLOUD_APP_TOKEN` or `APP_DATABASE_URL` exported earlier, for another application or before the [provision line](/cloud/concepts/turnzero-command/#running-on-your-machine) last ran, then wins over the value the command wrote. The platform refuses the old credential, or the calls reach the other application's data.

**Check.** In the shell that starts the run, list the names of the variables the file also sets. These commands print names alone, never a value: `env | cut -d= -f1 | grep -E '^(TURNZERO_CLOUD_|APP_)'` in a POSIX shell, or `(Get-ChildItem Env:TURNZERO_CLOUD_*, Env:APP_*).Name` in PowerShell. Any name the list shows is read from the shell, not from `.env`. Two names it can show are inputs of an unattended `provision`, and neither is in the file: `TURNZERO_CLOUD_MINTED_TOKEN` and `TURNZERO_CLOUD_ORIGIN`. `TURNZERO_CLOUD_APPLICATION` and `TURNZERO_CLOUD_API` are in the file, so they cause no harm while the shell has the same values.

**Remedy.** Clear every name the list shows, except the two inputs of an unattended `provision`. Also clear `TURNZERO_CLOUD_APPLICATION` where it gives another application, and `TURNZERO_CLOUD_API` where it gives a different origin from the one the command was given. `TURNZERO_CLOUD_API` gives an origin, such as `https://turnzero.ai`, not an application. Start the run in the same command, since a later command in the same shell can still inherit a cleared name.

In a Unix-style shell, such as bash or zsh: `env -u TURNZERO_CLOUD_APP_TOKEN -u APP_DATABASE_URL node --env-file=.env …`, one `-u` flag per stale name the list shows. In PowerShell, as one invocation: `Remove-Item Env:TURNZERO_CLOUD_APP_TOKEN, Env:APP_DATABASE_URL -ErrorAction SilentlyContinue; node --env-file=.env …`.

A new shell helps only where it is opened outside the tool's own process, not a tab or pane the tool's terminal forks from the current one, which can still inherit an exported name. [Run your app on your computer](/cloud/guides/run-your-application-on-your-machine/) lists the settings the command writes into the file, and `PORT`, which it does not write.
