> ## Documentation Index
> Fetch the complete documentation index at: https://launchdarkly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Evaluation reasons

<View title="Developer" />

<View title="Federal docs" />

<View title="EU docs" />

This topic explains how to use LaunchDarkly to determine why a context instance receives a given flag variation. It can be useful to have this information when you're diagnosing problems or doing analysis of the impact of different flags.

You can access this information programmatically from your SDK or from Data Export events. To learn more about Data Export, read [Data Export](/docs/integrations/data-export).

You can also view evaluation reasons on the context detail page. To learn how, read [The context details page](/docs/home/flags/context-details).

## Accessing flag variation information programmatically

For each of the SDK methods that you call to evaluate a feature flag, there is a corresponding `detail` method.

This method returns three pieces of information:

* The computed flag variation, which is what you get when you evaluate the flag
* The variation index, which is a zero-based integer indicating which variation was selected. For example, if the flag's possible variations are `A`, `B`, and `C`, in that order, and the computed variation is `C`, the variation index would be 2. This value is useful for tabulation, although in some cases, it may be absent. To learn more, read [Error conditions](#error-conditions).
* A `reason` object, which contains information about why that variation was selected. This data structure is described below.

<Card icon="rectangle-terminal" horizontal>
  Try it in your SDK: [Flag variation evaluation details](/docs/sdk/features/evaluation-reasons)
</Card>

## Understanding the reason data

In strongly-typed languages, the reason object is composed of specific classes. In other languages, it is a hash, such as a dictionary or object.

The JSON representation is the same in every language, so we will describe the reason object here as if it were a JSON object.

The reason object's only required property is `kind`. This describes the general reason that LaunchDarkly selected this variation. The possible values for `kind` are enums in the strongly-typed languages and strings in other languages.

These values are:

<table>
  <thead>
    <tr>
      <th>Value name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>OFF</code>
      </td>

      <td>
        Targeting is off and therefore returned its configured off value. This value appears on the flag's <strong>Targeting</strong> tab next to "If targeting is off, serve:".
      </td>
    </tr>

    <tr>
      <td>
        <code>FALLTHROUGH</code>
      </td>

      <td>
        Targeting is on, but the context did not match any targets or rules, so it returned the value that appears on the flag's <strong>Targeting</strong> tab under "Default rule." The "default rule" is not the same thing as the default value discussed in "Error conditions."
      </td>
    </tr>

    <tr>
      <td>
        <code>TARGET\_MATCH</code>
      </td>

      <td>
        The context key was specifically targeted for this flag in the "Individual targets" section.
      </td>
    </tr>

    <tr>
      <td>
        <code>RULE\_MATCH</code>
      </td>

      <td>
        The context that encountered the flag matched one of the flag's rules. In this case, the reason object also has these properties: <code>ruleIndex</code>, which is the positional index of the matched rule (0 for the first rule), and <code>ruleId</code>, which is the rule's unique identifier, and stays the same even if you rearrange the order of the rules.
      </td>
    </tr>

    <tr>
      <td>
        <code>PREREQUISITE\_FAILED</code>
      </td>

      <td>
        The flag had at least one prerequisite flag that either was off or did not return the desired variation. Because of this, the flag returned its "off" value. In this case, the reason object also has this property:{' '} <code>prerequisiteKey</code>: The key of the prerequisite flag that failed.
      </td>
    </tr>

    <tr>
      <td>
        <code>ERROR</code>
      </td>

      <td>The flag could not be evaluated, so the default value was returned.</td>
    </tr>
  </tbody>
</table>

`inExperiment` is an optional attribute on the `reason` object that indicates whether the context was evaluated as part of an experiment:

* If `inExperiment` is true, LaunchDarkly includes the event in experimentation analysis
* If `inExperiment` is false, LaunchDarkly does not include this attribute in the reason object

For a list of SDKs that support experiment allocation, read [Allocating experiment audiences](/docs/home/experimentation/allocation).

## Error conditions

If the `kind` is `ERROR`, it means that the SDK was unable to select any of the flag's variations. This is an abnormal occurrence.

In this case, the returned flag value is the default value that you specified in your code, which is the last parameter of the method you called to evaluate the flag, rather than any value that you specified on your flag's **Targeting** tab. In addition, the variation index will be `null/nil`.

When there is an error, the reason object also has an `errorKind` property which will be one of the following:

<table>
  <thead>
    <tr>
      <th>Property Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <code>CLIENT\_NOT\_READY</code>
      </td>

      <td>
        The client is not able to establish a connection to LaunchDarkly yet. If there is a persistent feature store, the store does not yet contain flag data.
      </td>
    </tr>

    <tr>
      <td>
        <code>FLAG\_NOT\_FOUND</code>
      </td>

      <td>The flag key did not match any known flag.</td>
    </tr>

    <tr>
      <td>
        <code>USER\_NOT\_SPECIFIED</code>
      </td>

      <td>The context was not provided or was invalid.</td>
    </tr>

    <tr>
      <td>
        <code>MALFORMED\_FLAG</code>
      </td>

      <td>
        There was an internal inconsistency in the flag data. For example, a rule specified a nonexistent variation. This is an unusual condition that might require assistance from LaunchDarkly's Support team.
      </td>
    </tr>

    <tr>
      <td>
        <code>WRONG\_TYPE</code>
      </td>

      <td>
        The application code requested the flag value with a different data type than it actually is. For example, the code asked for a boolean when the flag variation is a string. This can only happen in strongly-typed languages, such as Go, Java, and C#.
      </td>
    </tr>

    <tr>
      <td>
        <code>EXCEPTION</code>
      </td>

      <td>
        An unexpected error stopped flag evaluation. This could happen if you are using a persistent feature store and the database stops working. When this happens, the SDK always prints the specific error to the log.
      </td>
    </tr>
  </tbody>
</table>

## Understanding how Data Export events display

Calling any of the variation detail methods not only makes extra information available to your code, it also causes the SDK to include it in analytics events. You can view this information if you use the **Live events** page or Data Export.

To learn more, read [Live events](/docs/home/releases/live-events) and [Data Export](/docs/integrations/data-export).

The JSON representation of the reason data will be included in the feature evaluation event as an extra property called `reason`.

For instance, a `debug` event might look like this:

<CodeGroup>
  ```json title="JSON event data" expandable lines wrap theme={null}
  {
    "kind": "debug",
    "context": {
        "key": "example-context-key",
        "kind": "user",
        "name": "Sandy"
    },
    "creationDate": 1548195712000,
    "key": "example-flag-key",
    "version": 1000,
    "variation": 0,
    "value": true,
    "default": false,
    "reason": {
        "kind": "TARGET_MATCH",
        "inExperiment": true
    }
  }
  ```
</CodeGroup>