Merge troubleshooting pages into one

website/docs/feature-flag-tutorials/use-cases/how-to-create-feature-toggles.md

@@ -19,7 +19,7 @@ To create a feature flag in the Admin UI, do the following:
 
 [Activation strategies](/reference/activation-strategies) determine how and for whom a feature flag is enabled within a specific environment (for example, development, or production). To add an activation strategy to your feature flag in the Admin UI, do the following:
 
-1. Go to a feature flag, and select the [environment](/reference/environment) where you want to configure the flag.
+1. Go to a feature flag, and select the [environment](/reference/environments) where you want to configure the flag.
 2. Click **Add strategy** for that environment.
 3. In the **General** tab, select your rollout percentage. Optionally, you can set the strategy status to **Inactive** if you don't yet want the strategy to be exposed.
 4. Click **Save strategy**.

website/docs/troubleshooting.mdx

@@ -0,0 +1,129 @@
+---
+title: Troubleshooting
+---
+
+This guide helps you troubleshoot various situations you might encounter when working with Unleash feature flags, including flags not being returned, users not being exposed as expected, unexpected A/B test results, and CORS errors.
+
+## My feature flag is not returned or my users are not exposed
+
+If a feature flag isn't being returned by the Frontend API or Edge, or if users are not being exposed to a flag you believe is enabled, consider the following. By default, these endpoints do not return feature flags that are not enabled to save bandwidth.
+
+### Initial checks
+
+#### Verify feature configuration
+-   Ensure the feature flag has an [activation strategy](/reference/activation-strategies) associated with it that will evaluate to `true` for your given context.
+-   Confirm that the feature flag has been **enabled** in the specific environment your client application is using. (ref: [enabling a feature flag](/reference/feature-toggles))
+
+#### SDK `ready` event (frontend clients)
+-   Ensure your application, especially frontend clients, waits for the SDK to emit the `ready` event before calling `isEnabled('feature-flag')` or attempting to get variant information. Calling these functions too early might mean the client hasn't yet received the latest flag configurations from the server.
+
+### Token configuration
+
+#### Check token type
+-   To connect to the Frontend API or Edge, you **must** use a [Front-end API token](/reference/api-tokens-and-client-keys#frontend-tokens). Other token types will not work.
+
+#### Check token access
+-   The token's access configuration is **immutable after creation** and defines which feature flags it can access. The format of the token indicates its scope:
+    -   **Access to all projects (current and future):** Tokens starting with `*:` (e.g., `*:production:xyz123etc...`) provide access to flags in the specified environment across all projects.
+    -   **Access to a discrete list of projects:** Tokens starting with `[]:` (e.g., `[]:production:xyz123etc...`) grant access to a specific subset of projects in the given environment. You can see which projects a token has access to on the API Tokens page in the Unleash admin UI.
+    -   **Single project access:** Tokens starting with a project name (e.g., `my_fullstack_app:production:xyz123etc...`) are restricted to that project and environment.
+
+### Context and stickiness
+
+#### Gradual rollout strategy and stickiness
+-   When using a **gradual rollout** strategy, pay close attention to the [stickiness](/reference/stickiness) configuration.
+-   If the context provided by your SDK during flag evaluation **does not include the field specified for stickiness** (e.g., `userId`, `sessionId`, or a custom field), the gradual rollout strategy will evaluate to `false`. Consequently, the flag (or the "on" state for that user) will not be returned by the API.
+
+### Using the Unleash playground
+
+- Feature activation strategies can be combined in complex ways. The [Unleash Playground](/reference/playground.mdx) is an invaluable tool. You can use an access token along with various context values (input via the UI) to simulate how a flag will be resolved for different users and scenarios, helping you verify your configuration.
+
+### Alternative: Using variants for disabled/enabled states
+
+If you need to know about a flag regardless of whether it's "on" or "off" for a user (e.g., for analytics or UI rendering logic), consider using variants:
+
+-   First, enable the feature flag itself in the desired environment.
+-   Next, configure [strategy variants](/reference/strategy-variants) to represent "enabled" and "disabled" states. You can assign percentages to these variants (e.g., 50% "enabled", 50% "disabled").
+
+    ![Using enabled and disabled variants](/img/enabled-disabled-variants.png)
+    *This flag itself is enabled in development and adds a 50%/50% split between disabled/enabled variants. This is essentially the same as a gradual rollout of 50% but using variants.*
+
+-   Then, in your SDK, use the `getVariant()` call (or equivalent) instead of `isEnabled()`.
+-   This approach can also be combined with more complex constraint-based targeting.
+
+    ![Using enabled and disabled variants with constraints](/img/enabled-disabled-variants-complex.png)
+    *This flag returns an "enabled" variant for clients with a specific `semver` and performs a percentage split for the remaining clients.*
+
+## My A/B tests are producing unexpected results
+
+If your A/B tests or experiments are producing unexpected results:
+
+#### Prerequisite check
+-   First, ensure the feature flag is being returned correctly by following the guidance in the "[My feature flag is not returned or my users are not exposed](#my-feature-flag-is-not-returned-or-my-users-are-not-exposed)" section above.
+
+#### Verify gradual rollout percentage
+-   Check the rollout percentage of your [gradual rollout activation strategy](/reference/activation-strategies). If you intend to include 100% of your user base in the A/B/n test, ensure the rollout percentage is set to 100%.
+
+#### Check stickiness and context
+-   Revisit the [stickiness](/reference/stickiness) configuration.
+    -   If using default stickiness, confirm that either `userId` or `sessionId` (or both, depending on your setup) is consistently provided in the Unleash context from your application.
+    -   If the context provided during flag evaluation does not include the field used for stickiness, the gradual rollout strategy will evaluate to `false`, and the user will not be part of the A/B test population for that flag.
+
+#### Ensure variants are correctly configured
+-   Refer to the documentation on [feature flag variants](/reference/feature-toggle-variants).
+-   For a simple 50-50 A/B test, your variants should be configured accordingly (e.g., two variants, "A" and "B", with appropriate weighting or rollout distribution if not handled by a parent strategy).
+
+    ![An example of variants configured for an A/B test](/img/troubleshooting-flag-abn-test-unexpected-result-variants.png)
+
+#### Double-check SDK code for variant handling
+-   Verify that your application code correctly handles the feature flag variant response. Consult your specific SDK's documentation.
+-   For example, using the [Unleash React SDK](/reference/sdks/react), you might follow the [check variants](/reference/sdks/react#check-variants) section. Given the example variants "A" and "B", your code might look like this:
+
+    ```tsx
+    import { useVariant } from '@unleash/proxy-client-react';
+
+    export const TestComponent = () => {
+      const variant = useVariant('ab-test-flag'); // 'ab-test-flag' is your feature flag name
+
+      if (variant.name === 'A') {
+        return <AComponent />;
+      } else if (variant.name === 'B') {
+        return <BComponent />;
+      }
+      // Fallback or default component if the flag is off or variant is not recognized
+      return <DefaultComponent />;
+    };
+    ```
+
+#### Use the Unleash playground
+-   If results are still unexpected, use the [Playground](/reference/playground.mdx) to simulate different user contexts and verify that the feature flag and its variants are resolving as intended.
+
+## My requests are blocked due to CORS issues
+
+Cross-Origin Resource Sharing (CORS) issues can prevent your client-side application from communicating with the Unleash API or Edge. Browsers enforce CORS as a security measure. If you see errors like "No 'Access-Control-Policy' header is present on the requested resource," it's likely a CORS misconfiguration.
+
+### Configuring CORS in the Unleash admin UI (for Unleash server)
+
+-   Navigate to **Settings** in the Unleash Admin Dashboard.
+-   Select **CORS Origins**.
+-   Define the allowed origins (e.g., `https://your-app.com`).
+    -   **For troubleshooting:** You can temporarily set the allowed origin to `*` (a single asterisk) to allow all origins. This helps confirm if CORS is the root cause.
+    -   **Important Security Note:** Using `*` in production is generally discouraged. Always restrict origins to only those that require access.
+-   These settings can also be managed via the [Unleash API](https://docs.getunleash.io/reference/api/unleash).
+
+### Configuring CORS for Unleash Edge
+
+If you are using Unleash Edge, CORS headers are typically configured via command-line flags when starting the Edge instance:
+
+-   To allow a specific origin:
+    ```bash
+    unleash-edge edge --cors-origin "[https://your-application.com](https://your-application.com)"
+    ```
+-   You can specify multiple domains as a comma-separated list or by using the `--cors-origin` flag multiple times.
+-   Other CORS-related headers (e.g., `Access-Control-Allow-Headers`, `Access-Control-Allow-Methods`) can also be set via command-line arguments. Refer to the Unleash Edge deployment documentation for details.
+
+### Verifying the `Access-Control-Allow-Origin` header
+
+You can use the `curl` command-line tool to inspect the response headers from your Unleash instance and verify the CORS configuration. Replace `<host>` and `<endpoint>` with your Unleash server URL and a relevant API endpoint (e.g., the frontend API endpoint).
+
+```bash

website/docs/using-unleash/troubleshooting/cors.md

@@ -1,6 +0,0 @@
----
-title: My requests are being blocked by CORS
----
-
-1. Make sure you've configured CORS access in Unleash admin UI settings as defined in the [Unleash CORS Policy docs](/reference/front-end-api#configure-cross-origin-resource-sharing-cors). These settings can be changed in the Unleash Dashboard under **Settings -> CORS Origins** or by using the [API](/reference/api/unleash/set-ui-config). Allowing all origins (using a single asterisk) will address this matter and is a great starting point when troubleshooting the behavior.
-1. When receiving "**No 'Access-Control-Policy' header is present on the requested resource**", using the command `curl -I https://<host>/<endpoint>` will allow us to verify that the response includes the header `Access-Control-Allow-Origin: *`.

website/docs/using-unleash/troubleshooting/flag-abn-test-unexpected-result.md

@@ -1,34 +0,0 @@
----
-title: My feature flag is returning unexpected results in my A/B/n test
----
-
-Occasionally, users might come across a situation where a feature flag is returning unexpected results when running an A/B/n test.
-
-The first thing to look into is your feature configuration.
-
-If you're unsure whether the feature flag is being properly returned, you can go through the steps in this troubleshooting guide before proceeding: [My feature flag is not returned in the Frontend API/Edge/Proxy](/using-unleash/troubleshooting/flag-not-returned.md).
-
-1. Verify the rollout percentage of your gradual rollout [activation strategy](/reference/activation-strategies). If you would like to target 100% of your user base on your A/B/n test, confirm that your rollout percentage is set to 100%.
-2. Check the [stickiness](/reference/stickiness) value. If you're using default stickiness, confirm that either `userId` or `sessionId` are part of your context to ensure consistent results. Besides, if the provided context does not include the field used in the stickiness configuration, the gradual rollout strategy will be evaluated to `false` and therefore it will not be returned by the API.
-3. Ensure that your variants are correctly configured. You can refer to [feature flag variants](/reference/feature-toggle-variants). For example, if you would like to run a simple 50-50 A/B test, then your variants should look similar to this: 
-
-![An example of variants configured for an A/B test](/img/troubleshooting-flag-abn-test-unexpected-result-variants.png)
-
-4. Double check that your code is correctly handling the feature flag variant response. You can refer to your SDK documentation for more information on how to handle feature flag variants. For example, if you're using the [Unleash React SDK](/reference/sdks/react), you can follow the [check variants](/reference/sdks/react#check-variants) section of the documentation. Given the example variants above, this could look like the following:
-
-```tsx
-import { useVariant } from '@unleash/proxy-client-react';
-
-export const TestComponent = () => {
-  const variant = useVariant('ab-test-flag');
-
-  if (variant.name === 'A') {
-    return <AComponent />;
-  } else if (variant.name === 'B') {
-    return <BComponent />;
-  }
-  return <DefaultComponent />;
-};
-```
-
-Feature activation strategies can be combined in different ways, which may lead to complex scenarios. If you're still not seeing the results you expect, try using the [Playground](/reference/playground.mdx) to verify that the feature is properly configured and responding as expected.

website/docs/using-unleash/troubleshooting/flag-exposure.md

@@ -1,8 +0,0 @@
----
-title: My feature flag is enabled but all/some of our users are not exposed to it
----
-
-To confirm how users will have flags resolved, follow these steps:
-1. Ensure your application is waiting for the `ready` event: It could be that frontend clients are calling `isEnabled('feature-flag')` before they have the response from the server. In this case, you should defer isEnabled calls until the client has emitted the `ready` event.
-2. The [Unleash Playground](/reference/playground.mdx) was developed with this particular use case in mind. An access token can be used along with context values (passed in via the UI) to see how a flag will be resolved. 
-3. When using a **gradual rollout** strategy, be mindful of the **[stickiness](/reference/stickiness)** value. When evaluating a flag, if the provided context does not include the field used in the stickiness configuration, the gradual rollout strategy will be evaluated to `false`.

website/docs/using-unleash/troubleshooting/flag-not-returned.md

@@ -1,32 +0,0 @@
----
-title: My feature flag is not returned in the Frontend API/Edge/Proxy
----
-
-By default, these endpoints will not return feature flags that are not enabled. This is mainly to save on bandwidth but it makes it a bit difficult to debug when features are not being returned. 
-
-The first thing to look into is to validate that the feature is well configured and then check the token used from the SDK because it determines the set of accessible features. Last, verify that the context you're providing contains all the required data.
-
-1. Check that the feature is properly enabled: 
-    1. Verify that the feature has a strategy associated to it that will return true for your context (ref: [add a strategy](/reference/actication-strategies))
-    2. Verify that the feature has been enabled in the environment used by the client application (ref: [enabling a feature flag](/reference/feature-toggles))
-2. Check that your token is of the right [type](/reference/api-tokens-and-client-keys.mdx). To connect to the Frontend API, Edge or Proxy, you need to use a [Front-end token](/reference/api-tokens-and-client-keys#frontend-tokens)
-3. Check that your token has access to the feature flag. The **token access configuration is immutable post-creation** and defines the set of features that the token can access. The different [parts of a token](/reference/api-tokens-and-client-keys#api-token-format) determine what projects and environment can be accessed:
-    1. **Access to all projects (current and future)** - Tokens with a leading asterisk will provide access to all projects in a particular environment. For example, the token `*:production:xyz123etc...` will provide access to flags in the production environment of all projects.
-    2. **Access to a discrete list of projects** - Tokens with a leading set of square brackets (empty) will be given access to a subset of projects in a particular environment. The token will look similar to the following: `[]:production:xyz123etc...`. Which projects the token has access to can be found on the API Tokens page in the Unleash admin UI.
-    3. **Single project access** - Tokens that lead with a project name are bound to the specified project and environment. For example, `my_fullstack_app:production:xyz123etc...` will only have access to flags in the "my_fullstack_app" project as set in the production environment.
-4. When using a **gradual rollout** strategy, be mindful of the **[stickiness](/reference/stickiness)** value. When evaluating a flag, if the provided context does not include the field used in the stickiness configuration, the gradual rollout strategy will be evaluated to `false` and therefore it will not be returned by the API.
-5. Feature activation strategies can be combined in different ways, which may lead to complex scenarios. Try using the [Playground](/reference/playground.mdx) to verify that the feature is properly configured and responding as expected.
-
-
-If you want to return a flag no matter if it's disabled or enabled you can move the disabled/enabled information into the [strategy variants](/reference/strategy-variants).
-
-![enabled_disabled_variants](/img/enabled-disabled-variants.png 'Using enabled and disabled variants')
-
-This flag itself is enabled in development and adds 50%/50% split between disabled/enabled variants. This is essentially the same as a gradual rollout of 50% but using variants.
-Remember to use `getVariant` call instead of `isEnabled` call in your SDK.
-
-You can combine this approach with more complex constraint based targeting.
-
-![enabled_disabled_variants_complex](/img/enabled-disabled-variants-complex.png 'Using enabled and disabled variants with constraints')
-
-This flag returns enabled variant for the client with the explicit `semver` and performs percentage split for the remaining clients.

website/docusaurus.config.ts

@@ -804,23 +804,6 @@ class="header-github-link"
                             ],
                             to: '/understanding-unleash/data-collection',
                         },
-
-                        {
-                            from: '/how-to/how-to-troubleshoot-flag-exposure',
-                            to: '/using-unleash/troubleshooting/flag-exposure',
-                        },
-                        {
-                            from: '/how-to/how-to-troubleshoot-flag-not-returned',
-                            to: '/using-unleash/troubleshooting/flag-not-returned',
-                        },
-                        {
-                            from: '/how-to/how-to-troubleshoot-cors',
-                            to: '/using-unleash/troubleshooting/cors',
-                        },
-                        {
-                            from: '/how-to/how-to-troubleshoot-https',
-                            to: '/using-unleash/troubleshooting/https',
-                        },
                         {
                             from: [
                                 '/reference/deploy/environment-import-export',

website/sidebars.ts

@@ -90,6 +90,14 @@ const sidebars: SidebarsConfig = {
                             type: 'doc',
                             id: 'feature-flag-tutorials/use-cases/how-to-create-feature-toggles',
                         },
+                        {
+                            type: 'doc',
+                            id: 'how-to/how-to-schedule-feature-releases',
+                        },
+                        {
+                            type: 'doc',
+                            id: 'how-to/how-to-synchronize-unleash-instances',
+                        },
                         {
                             type: 'category',
                             label: 'Use Cases',
@@ -579,6 +587,7 @@ const sidebars: SidebarsConfig = {
                         'using-unleash/deploy/configuring-unleash',
                         'using-unleash/deploy/upgrading-unleash',
                         'using-unleash/deploy/license-keys',
+                        'using-unleash/deploy/https',
                     ],
                 },
                 {
@@ -651,48 +660,7 @@ const sidebars: SidebarsConfig = {
                         },
                     ],
                 },
-                {
+                'troubleshooting',
-                    label: 'Troubleshooting',
-                    type: 'category',
-                    link: {
-                        type: 'doc',
-                        id: 'using-unleash/troubleshooting/cors',
-                    },
-                    items: [
-                        'using-unleash/troubleshooting/cors',
-                        'using-unleash/troubleshooting/https',
-                        'using-unleash/troubleshooting/flag-exposure',
-                        'using-unleash/troubleshooting/flag-not-returned',
-                        'using-unleash/troubleshooting/flag-abn-test-unexpected-result',
-                    ],
-                },
-                {
-                    label: 'How-to guides',
-                    type: 'category',
-                    link: {
-                        type: 'generated-index',
-                        title: 'How-to guides',
-                        description: 'Step-by-step recipes for you to follow.',
-                        slug: '/how-to',
-                    },
-                    items: [
-                        {
-                            label: 'Feature flags, strategies, context',
-                            type: 'category',
-                            link: {
-                                type: 'generated-index',
-                                title: 'How-to: general Unleash tasks',
-                                description:
-                                    'Guides for how to perform general Unleash tasks.',
-                                slug: '/how-to/misc',
-                            },
-                            items: [
-                                'how-to/how-to-schedule-feature-releases',
-                                'how-to/how-to-synchronize-unleash-instances',
-                            ],
-                        },
-                    ],
-                },
             ],
         },
         {

website/vercel.json

@@ -131,6 +131,11 @@
       "destination": "/reference/feature-toggles#set-a-naming-pattern",
       "permanent": true
     },
+    {
+      "source": "/how-to/",
+      "destination": "/what-is-a-feature-flag",
+      "permanent": true
+    },
     {
       "source": "/how-to/how-to-add-users-to-unleash",
       "destination": "/reference/rbac",
@@ -832,13 +837,33 @@
       "permanent": true
     },
         {
-      "source": "/how-to/how-to-troubleshoot-cors",
+      "source": "/how-to/how-to-troubleshoot-flag-not-returned",
-      "destination": "/using-unleash/troubleshooting/cors",
+      "destination": "/using-unleash/troubleshooting/flag-not-returned",
       "permanent": true
     },
     {
-      "source": "/how-to/how-to-troubleshoot-https",
+      "source": "/using-unleash/troubleshooting/cors",
-      "destination": "/using-unleash/troubleshooting/https",
+      "destination": "troubleshooting",
+      "permanent": true
+    },
+        {
+      "source": "/using-unleash/troubleshooting/flag-abn-unexpected-results",
+      "destination": "troubleshooting",
+      "permanent": true
+    },
+        {
+      "source": "/using-unleash/troubleshooting/flag-exposure",
+      "destination": "troubleshooting",
+      "permanent": true
+    },
+        {
+      "source": "/using-unleash/troubleshooting/flag-not-returned",
+      "destination": "troubleshooting",
+      "permanent": true
+    },
+    {
+      "source": "/how-to/troubleshooting/https",
+      "destination": "/using-unleash/deploy/https",
       "permanent": true
     },
     {