Skip to main content

Troubleshoot secrets

Check scope, credential, sensitivity level, and value shape in that order. This sequence isolates most secret failures quickly.

Start with five checks#

  1. Confirm the organization and site selected in Console.
  2. Confirm the scope by location: site Secrets, or Operate → Secrets inside the intended app.
  3. Confirm the intended account is signed in.
  4. Confirm the secret type's sensitivity level allows the caller to read the value.
  5. Confirm the value satisfies the secret type's JSON schema.

Match the symptom#

401 reading a secret#

The session or runtime credential is missing or expired, or the secret type's sensitivity level needs a signed-in caller. Sign in again in Console, or refresh the runtime credential.

403 reading a secret#

The caller can't read this sensitivity level. A site user can't read sensitive values, even with their own API key; read the secret as a member of your organization, or from a Function.

The secret is missing from Console#

Check the selected site or app and the exact key. Open the site's Secrets for site scope, or the app's Operate → Secrets for app scope, then use Search secrets....

Validation error on save#

The values don't match the selected secret type's schema. Reopen Edit Secret, correct the highlighted configuration field, and choose Save Changes.

Invalid key#

Keep the key within 255 characters. Console accepts letters, numbers, _, and -, and doesn't accept ..

Duplicate-key conflict#

The key already exists in the selected site or app. Search for it and use Edit instead of Create Secret.

A tagged create fails#

The secret may already exist, because the backend saves it before resolving tags. Search for the same key and scope before retrying, then edit it after fixing the tags.

An update unexpectedly changes tags or scope#

Use Edit Secret from the same site or app page; Console resends the tags, and the app slug for app scope, in the full update.

A secret type won't delete#

Remove the secrets that reference it first. A system type can't be deleted.

The sensitivity level can't be changed#

The level is immutable. Create a new type with the level you want.

The app value isn't returned#

An app secret overrides a site secret only when the request supplies the app slug. Python substitutes its configured app_slug when app is omitted.

Changed access still returns a cached result#

The resolved-value cache doesn't include the caller's identity, so don't use a repeated read as proof of per-caller authorization.

A 5xx response#

Capture a minimal, redacted request with its identifier, UTC time, route, and scope before contacting TaruviBase support.

Confirm resolution#

When a read returns a value you did not expect:

  1. Open site Secrets and search the key to inspect the site value.
  2. Open the app's Operate → Secrets page and search the key to inspect the app-scoped entry. That list deliberately excludes inherited site entries.
  3. Runtime SDK reads with an app slug still use app-over-site fallback even though the Console app list shows app scope only.

Check a write#

  1. Open site Settings → Secret Types and inspect the type's schema.
  2. Confirm the value fields and types satisfy the schema.
  3. Confirm the key is within 255 characters, satisfies the Console input rules, and is unique within its scope.
  4. Reopen Edit Secret from the same site/app page; keep every required tag and configuration field.
  5. Choose Save Changes, then reopen the secret to verify it.

Confirm the fix#

After applying a change, return to the same Console site/app location, refresh, and confirm the expected result:

  • A read returns 200 with the expected value, or 404 if you intended a deletion.
  • A created secret appears after Create Secret succeeds.
  • An edited secret shows the new value after Save Changes succeeds.
  • A credential or site-access fix returns 200/201 for the intended caller, while an unauthenticated or sensitivity-denied caller still receives 401/403.

If the same error recurs with a minimal request, capture the diagnostics below and contact TaruviBase support.

Share safe diagnostics#

Keep the HTTP status, the error body, the UTC time, the site hostname, and the app slug. If a key name is sensitive, hash the key locally and share the digest instead of the raw name. Do not attach any secret value, credential, token, or raw customer record.