Secrets

These entries start from what your code or a refusal shows about a value you stored. 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's key stays at the 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 only where the manifest's settings member binds its name, and only from the environment's next deploy or promote.

Check. list_secrets shows the name's row, and its settings member lists the settings the manifest binds to it, empty where none does. list_upstreams 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 seven settings Run locally lists, and no bound setting.

Remedy. For the key of an external application programming interface (API), call the API through the gateway. Or declare the upstream with settings, so an unchanged software development kit (SDK) reads its base URL and an egress key (An unchanged SDK). For a value your code must read itself, bind it as Bind a value to a setting shows. Store it at each environment's scope of the application, submit the manifest, and deploy again.

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

Cause. The command line that store_secret or rotate_secret returned presented a grant the platform does not have. A grant lasts minutes, and the platform removes it some time after it expires, or with its application or account. Or the grant in the line was changed, for example cut short when the line was copied.

Check. The command printed store_secret refused (HTTP 401): authentication_required, or the same for rotate_secret. Its explanation opens "The grant this request presented was not accepted". The command ended with status 3, and nothing was written.

Remedy. Call store_secret or rotate_secret from your tool again, and run the fresh command that call returns, whole and as given, before its expires_at. Signing in again does not help, because the refusal is about the line's grant and not about your account.

The secret line is refused secret_grant_expired

Cause. The line ran after the expires_at its call returned. A grant lasts a few minutes from the call, so a line 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, and ended with status 3. Nothing was written, and a stored value is unchanged.

Remedy. Call store_secret or rotate_secret from your tool again, and run the fresh command before its expires_at. Where you type the value yourself, have the value ready before your tool makes the call.

The secret line is refused secret_grant_spent

Cause. A grant can be used once. The line's grant had already been used, so this run wrote nothing. Most often the same line ran twice, and its first run stored the value. Where the line's first run is refused this way, someone else used a copy of the grant first, and the value stored under the name may not be yours.

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

Remedy. Do not run the same line again. Where an earlier run of the line ended with status 0, the value is stored and nothing more is needed. Where list_secrets shows no write at the time the line first ran, or the first run was refused, call store_secret or rotate_secret from your tool again and run the fresh command. That write replaces the value 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 line. The line was changed to give another of them, for example another --name, or secret rotate in place of secret store. Or the grant was presented somewhere else, such as another management action or a storage route.

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

Remedy. Run the line exactly as the call returned it, before its expires_at. For another name or scope, call store_secret or rotate_secret from your tool again for that name and scope, and run the command it returns.

The provision line is refused

Cause. The line a submit_manifest call naming local_run returns contains a secret grant that re-mints each of the application's two development credentials once, within five minutes. secret_grant_spent means the line already ran, or someone else used a copy of its grant first. secret_grant_expired means the line ran after its expires_at. secret_grant_not_admitted means the line was changed, for example to give another --application.

Check. The command printed rotate_secret refused (HTTP 403): followed by one of the three names, and ended with status 3. Nothing was re-minted, and the environment file is as it was. Where the refusal came on the second request, the command ended with status 2 and said that the database credential was re-minted and not written. The remedy is the same.

Remedy. Call submit_manifest from your tool again with the application, its manifest, and local_run, and run the line it returns as given. That line re-mints both credentials, so a value someone else received stops working. Where a response to a request that named local_run has no provisioning, the platform could not prepare the line, and the same call again returns one.

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. A TURNZERO_CLOUD_TOKEN or APP_DATABASE_URL exported earlier, for another application or before the provision line last ran, takes precedence over the value the line wrote. The platform then 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 contains a different origin from the one the line was given. TURNZERO_CLOUD_API contains an origin, 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_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_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 locally lists the settings the line writes into the file, and PORT, which it does not write.