Skip to content
FlagSwiftDocs

Troubleshooting

The problems people hit most, and how to fix them. Quote the X-Request-Id of a failing response when you ask for help.

A flag is always off in my app#

Check, in order: the flag is on in the environment the key points at; the key is for the right project; the SDK is sending the identifier the flag buckets by (otherwise you get NO_IDENTIFIER); and nothing is holding the emergency stop. The inspector on the flag's Targeting tab shows the decision for a given person, and the server endpoint with explain=true shows the reason.

I get 401 AUTH_INVALID_API_KEY#

The key is wrong, revoked or expired, or belongs to another installation. Copy it again from the API Keys page (if key storage is on) or rotate it. Check there is no trailing space, and that the header reads Authorization: Bearer <key>.

I get 403 on the server endpoint#

The server endpoint needs a server or admin key. A client key is refused there. A key limited to one environment also cannot ask for another.

I get 402 FEATURE_NOT_IN_PLAN or PLAN_LIMIT_REACHED#

This is FlagSwift Commercial. The action is not part of your organization's plan, or you are at the cap for something like projects, members or API keys. Ask the organization's owner to upgrade from Plan and usage. Flags that already exist keep serving whatever the plan; see Plans and limits. The Evaluation API used by SDKs never answers 402.

My SDK stopped refreshing after a 401 or 403#

A 401 or 403 is terminal in every SDK: the key is wrong, revoked or expired, or limited to another environment. The SDK keeps serving the last good flags and does not keep retrying. Fix or rotate the key and restart the app.

ENV_NOT_FOUND or a missing environment#

A key that covers the whole project must send the environment, as environment in an SDK or ?env= in the API. Use the environment's name, for example production, not its display name.

I get 429 RATE_LIMITED#

Wait for the Retry-After seconds. Client keys are limited per key and visitor address. The limit is 600 requests a minute per key. If a legitimate app needs more, use more than one key or cache evaluations in your app. SDKs already back off and poll every 30 seconds, so a flood usually means a check in a render loop.

Forgot password says Too many reset requests#

The server allows 3 reset requests an hour for one email from one address, and 20 an hour from one address (an office or VPN shares that). Reset links themselves can be submitted 10 times per 15 minutes per address. Wait for Retry-After; an operator cannot change these limits, only turn all rate limiting off with RATE_LIMIT_ENABLED=false (see Self-hosting, Rate limits).

I never got the verification email#

Check spam first. On the Check your email screen choose Resend email (it unlocks 60 seconds after the last send), or type your email on the sign-in page with the right password to have a fresh link sent. The server allows 5 verification emails an hour for one email from one address, and 20 an hour from one address; past that, wait for Retry-After. If the screen says why it could not send, tell your operator: the usual causes are no email provider configured, a sending domain that is not verified (MAIL_FROM) or APP_URL not set, because the link is only built from APP_URL. Links expire after 24 hours; an expired one opens a page where you can ask for a new link. Wrong address? Sign up again with the right one: an unverified sign-up is replaced and the old link stops working.

Sign-in says Verify your email to sign in#

The account was created by signing up and its email address has not been verified yet, so the API answers 403 with EMAIL_NOT_VERIFIED (only after the password was right). Open the link in the verification email, or use Resend email. Invited members and older accounts never see this. FlagSwift only verifies the mailbox, not your identity.

The browser blocks my request#

Only the client endpoint allows cross-origin calls. The server endpoint sends no CORS headers on purpose, so never call it from a browser. Use a client key with /api/v1/evaluation/client.

A change takes a while to show up#

Server SDKs poll every 30 seconds by default and the server caches configuration for up to 30 seconds. With several instances another instance may serve the old value until its cache expires. Turn on streaming (JavaScript, React and Node SDKs) to refresh the moment a flag changes, or lower refreshInterval if you need it faster.

I cannot copy an API key from the list#

Copying needs an administrator, an active key, and API_KEY_ENCRYPTION_KEY to have been set when the key was created. Older keys cannot be recovered; rotate them.

A flag shows as unused but my backend uses it#

Flags evaluated locally by a server SDK are not counted, so they can look unused or stale. Check a flag's last change and dependents before archiving it.

I get APPROVAL_REQUIRED#

The environment requires approval. Propose a release from the flag's Releases tab and ask a release manager or administrator to approve it.