Skip to Content
Troubleshooting

Troubleshooting

Use this page to quickly identify why a flag result is different from what you expect.

Fast Diagnostic Checklist

Run these in order before deeper debugging:

  1. Confirm the SDK key is from the correct project.
  2. Confirm the evaluated environment is correct (development vs production).
  3. Confirm the flag key matches exactly (case-sensitive).
  4. Confirm fallback values are set in code.
  5. Confirm targeting rules actually match the runtime context.

Symptom -> Likely Cause -> Fix

SymptomLikely causeFix
Flag always falseWrong flag key or missing fallbackVerify key spelling and features config
Rule works for some users onlyMissing userId or context mismatchLog context payload before evaluation
”Unauthorized”Invalid key type or copied with whitespaceRe-copy key from project settings
Dashboard changed but app did notEnvironment mismatch or client cacheVerify environment, refresh, re-fetch
Server/client results differDifferent keys or context inputsCompare key, env, and context side by side

Validate Runtime Context

Targeting is only as accurate as the context you send.

const context = {
  userId: user.id,
  email: user.email,
  plan: user.plan,
  country: user.country,
}
 
console.log('supaship-context', context)
const value = await client.getFeature('new-navigation', { context })

Checklist:

  • userId is stable across sessions
  • data types match rule expectations ("123" vs 123)
  • attributes used in rules are always present

Common Configuration Mistakes

1) Wrong environment

Your code may evaluate in development while dashboard edits are in production.

const client = new SupashipClient({
  sdkKey: process.env.NEXT_PUBLIC_SUPASHIP_SDK_KEY,
  environment:
    process.env.NODE_ENV === 'production' ? 'production' : 'development',
  features: { 'new-navigation': false },
})

2) Missing or incorrect fallback

Always define expected local fallback values to avoid ambiguous behavior during network delays or setup issues.

3) Key type mismatch

  • Client apps: use -client key
  • Backend services: use -server key

Rollout Debug Playbook

When a rollout behaves unexpectedly:

  1. Freeze rollout percentage (do not continue ramp-up).
  2. Export the exact rule set used in production.
  3. Compare expected vs actual context samples.
  4. Test with two known users: one should match, one should not.
  5. Re-enable rollout only after deterministic test results.

Performance and Reliability Tips

  • Batch evaluations when possible.
  • Avoid evaluating flags repeatedly for the same context in a single render path.
  • Keep context payload lean and stable.
  • Add telemetry around evaluation duration and error rates.

Still Stuck?

Include this info when contacting support:

  • project name
  • environment
  • flag key
  • sanitized context example
  • expected result vs actual result
  • timestamp and timezone

Contact: support@supaship.com

Last updated on
Best Practices