Why does posthog.getFeatureFlag() return undefined on the first page load?

By Ohad Krispin, founder of VibeRaven · LinkedIn

posthog.getFeatureFlag() returns undefined when the flags have not loaded yet. PostHog's docs say flags are available immediately on most pages, except the first time a user visits, because the values come from a request that has not finished. Code that reads a flag right after posthog.init() therefore sees undefined for a new visitor and takes the "flag off" branch. Read the flag inside posthog.onFeatureFlags(), or in React pass a default as the second argument of useFeatureFlagEnabled. To have the value before the first request, evaluate flags on the server and pass them to posthog.init as bootstrap, with the same distinct ID. Reproduced with posthog-js 1.444.0 on 2026-10-31.

What does the call return before and after the flags load?

In a test of posthog-js 1.444.0 in jsdom on 2026-10-31, a local server answered the flags request after 150 ms and the test called reloadFeatureFlags() to send it. Read right after init, the flag was undefined. Read inside onFeatureFlags, it was true. With the same flag passed as bootstrap, it was true right after init.

new visitor, right after init:      getFeatureFlag("new-pricing") -> undefined
new visitor, in onFeatureFlags:     getFeatureFlag("new-pricing") -> true
with bootstrap, right after init:   getFeatureFlag("new-pricing") -> true

How do I wait for flags in plain JavaScript or React?

PostHog's docs say to use the onFeatureFlags callback to wait for the flag request to finish. For React, the docs say the useFeatureFlagEnabled hook returns boolean | undefined while flags are loading or absent, and that passing a default value as the second argument avoids handling undefined. A default of false shows the old branch until the flags arrive, which can flash the old version to a new visitor.

posthog.onFeatureFlags(() => {
  if (posthog.getFeatureFlag("new-pricing")) showNewPricing()
})

// React
const showNew = useFeatureFlagEnabled("new-pricing", false)

How do I bootstrap flags from the server in Next.js?

PostHog's bootstrapping guide gives the steps: get or create the distinct ID the client uses, call getAllFlags() for that ID on the server, put the flags and the ID in the response that renders the page, and pass both to bootstrap when the client starts. It says to use the same distinct ID on the server and the client, because variant assignment is deterministic for an ID.

Three caveats from the same guide: the next complete flags response replaces the bootstrapped values, only enabled values are kept (true or a non-empty string, false is dropped), and reset() clears bootstrapped flags.

// server, with posthog-node
const flags = await serverClient.getAllFlags(distinctId)

// client
posthog.init(token, {
  api_host: "https://us.i.posthog.com",
  bootstrap: { distinctID: distinctId, isIdentifiedID: true, featureFlags: flags },
})

Checklist

How to fix it, then check the fix

Find every flag read in the client code:

grep -rnE "getFeatureFlag|isFeatureEnabled|useFeatureFlag" --exclude-dir=node_modules --exclude-dir=.next .

02Treat undefined as "not loaded yet", not as "off". Show a neutral or loading state until the flags arrive.
03Move the read into posthog.onFeatureFlags(), or in React give useFeatureFlagEnabled a default.
04If the first render must not flash, bootstrap: call getAllFlags() on the server, pass the same distinct ID and the flags to posthog.init, and set isIdentifiedID to whether that ID is an identified user.
05Do not expect false to survive bootstrapping. Only true or a non-empty string is seeded, so treat a missing key as off.
06Test as a new visitor in a private window. Read the flag in the console right after load, then after the flags request in the Network panel has finished: the first read may be undefined, the second should have the value. With a bootstrap, both should.

Sources

Official docs behind this checklist

Browse all launch guides · Read resources · How to make and check your next change

FAQ

FAQ for builders before launch

Why is it fine on the second page load?

PostHog says flags are available immediately for most pages except the first time a user visits, so a returning visitor does not see the gap.

Is undefined the same as false?

No. PostHog's hook docs say the value is undefined while flags are loading or absent, so it can also mean the flag does not exist for that user. Check onFeatureFlags before you read it as off.

Do I still need the flags request after bootstrapping?

Yes, unless you turned automatic requests off. The next complete flags response replaces the bootstrapped values, and if you disable the automatic requests the bootstrapped values stay as they are.