Troubleshooting API Gateway

If API Gateway is not performing as expected, you might need to troubleshoot issues.

Request error handling

When requests cannot be fully satisfied, the API Gateway service gives the caller accurate, practical error information. The API Gateway service honors the GraphQL error specification with some custom extensions for greater specificity.

Syntax Validation

Before processing any portion of a request, the service parses its syntax. If the request is not valid GraphQL, or if it does not conform to the schema, the service returns a response with the syntax errors, including line and column positions whenever possible.

Examples of syntax errors include:

• Unbalanced parentheses, braces, brackets, and quotation marks
• References to fields that do not exist

The GraphQL error specification requires reporting these errors to the caller by line and column in the request.

Structural Validation

If the request passes syntax validation, the service evaluates the request for structural validity, which checks for errors not expressible with the GraphQL type system. Structural error examples include:

• Restrictions on type values, such as:
  • A string may not be empty
  • An integer must be positive
• Constraints on input objects, such as:
  • Exactly one of two or more entries must be present
• Existence of values in a known set, such as:
  • A named sensor must exist
• References to fields that cannot be satisfied in the current environment, such as:
  • A sensor does not exist

The GraphQL extensions error field for custom fields contains these errors.

Error Extensions

Errors that pertain to a specific field in the request are identified by a fieldPath entry in the extensions object. Similar to the path entry on the GraphQL error type, the fieldPath consists of a list of strings and integers which indicate keys in objects and offsets in lists, respectively. The root of the fieldPath is the request field that triggered the GraphQL error.

The extensions object may also have these fields:

For example, with the following syntactically valid request:

1
2
3
4
5
6
7
8
9
10
{
  endpoints {
    edges {
      node {
        name
        serialNumber
      }
    }
  }
}

If the serial number is not available in the underlying data store, the API Gateway service returns a response including an extended error that the value does not exist:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "errors": [
    {
      "message": "Invalid request",
      "path": ["endpoints"],
      "extensions": {
        "fieldPath": ["edges", "node", "serialNumber"],
        "code": "validation_exists",
        "message": "must refer to an existing sensor",
        "context": {
          "source": "tds"
        }
      }
    }
  ]
}

Invalid argument errors contain an extended argumentErrors entry. The value of that entry is a list of objects that may have the following entries:

For example, with the following request that does not define a name or path value:

1
2
3
4
5
6
7
8
9
{
  endpoints(filter: {filters: [{memberOf: {name: ""}}, {path:""}]}) {
    edges {
      node {
        name
      }
    }
  }
}

The API Gateway service returns a response including both errors stating a value is a required:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "errors": [
    {
      "message": "Invalid request",
      "path": ["endpoints"],
      "extensions": {
        "argumentErrors": [
          {
            "code": "validation_required",
            "path": ["filter", "filters", 0, "memberOf", "name"]
          },
          {
            "code": "validation_required",
            "path": ["filter", "filters", 1, "path"]
          }
        ]
      }
    }
  ]
}

Extended errors may identify argument errors within sub-fields. For example, the following request specifies a non-existent sensor name:

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  endpoints {
    edges {
      node {
        sensorReadings(sensors:[{name: "A Non-Existent Sensor"}]) {
          columns {
            values
          }
        }
      }
    }
  }
}

The API Gateway service returns a response including the sub-field error that the value does not exist:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "errors": [
    {
      "message": "Invalid request",
      "path": ["endpoints"],
      "extensions": {
        "fieldPath": ["edges", "node", "sensorReadings"],
        "argumentErrors": [
          {
            "code": "validation_exists",
            "path": ["sensors", 0, "name"]
          }
        ]
      }
    }
  ]
}

Whenever possible, the response includes the valid portions of a query. For example, the following request references a valid sensor (Custom Tags) and a not valid sensor (A Non-existent Sensor):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  endpoints {
    edges {
      node {
        name
        ipAddress
        os {
          generation
        }
        sensorReadings(sensors: [{name: "Custom Tags"}, {name: "A Non-existent Sensor"}]) {
          columns {
            sensor {
              name
            }
            name
            values
          }
        }
      }
    }
  }
}

The response includes the error from A Non-Existent Sensor not being found, and all information that can otherwise be returned from the Custom Tags sensor:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
{
  "errors": [
    {
      "message": "sensors: (1: (name: must refer to an existing sensor.).).",
      "path": [
        "endpoints"
      ],
      "extensions": {
        "argumentErrors": [
          {
            "code": "validation_exists",
            "context": {
              "source": "tds"
            },
            "message": "must refer to an existing sensor",
            "path": [
              "sensors",
              1,
              "name"
            ]
          }
        ],
        "fieldPath": [
          "edges",
          "node",
          "sensorReadings"
        ]
      }
    }
  ],
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "example-host",
            "ipAddress": "192.0.2.10",
            "os": {
              "generation": "Windows 10"
            },
            "sensorReadings": {
              "columns": [
                {
                  "sensor": {
                    "name": "Custom Tags"
                  },
                  "name": "Custom Tags",
                  "values": [
                    "custom-tag-1",
                    "custom-tag-2"
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  }
}

Similar to lists in the fieldPath referring to offsets in lists, if an error occurs on an item in a list, the error message might refer to the list offset instead of the field name. In the above response, the message refers to item 1 in the list; because list numbering starts at 0, this points to the second sensor (A Non-existent Sensor).

Error codes

General error codes include:

Syntax error codes include:

Structural error codes include:

Issue: error message for enumerated value displays the value in the request

For enumerated type fields in requests, if you pass the enumerated value in quotation marks, the response error message appears to state that you must pass that value. For example, with the following request, any (a boolean field) is set to "false" and visibility (an enumerated type) is set to "ALL" (in quotation marks):

1
2
3
4
5
6
7
8
9
10
11
12
mutation createActionGroup {
  actionGroupCreate(
    input: {any: "false", computerGroups: [{name: "Example Computer Group"}], name: "Example Action Group", visibility: "ALL"}
  ) {
    group {
      id
    }
    error {
      message
    }
  }
}

The response constrains validation error messages similar to the following because the validation engine parses "false" and "ALL" as non-enumerated values, and requires that they be passed in the request without quotation marks.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "errors": [
    {
      "message": "Boolean cannot represent a non boolean value: \"false\"",
      "extensions": {
        "code": "GRAPHQL_VALIDATION_FAILED"
      }
    },
    {
      "message": "Enum \"ActionGroupVisibility\" cannot represent non-enum value: \"ALL\". Did you mean the enum value \"ALL\"?",
      "extensions": {
        "code": "GRAPHQL_VALIDATION_FAILED"
      }
    }
  ]
}

Do one of the following:

• Pass the value as a JSON variable definition.

• Pass the value in your request without quotation marks.

• If using the Query Explorer, enter an enumerated type field and a colon, press Shift + Space when your cursor is after the colon, then select an enumerated value.

Issue: ResourceExhausted error in response to valid query request

Query requests that retrieve a large amount of information in the response might return a ResourceExhausted error, due to the size of the response in bytes being too large to return. For example, the following request specifies returning the first 99999 results, and requests multiple fields with the potential to return many results per field, increasing the overall size of the response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
query endpointsLargePagination {
  endpoints(first: 99999) {
    edges {
      node {
        id
        eidFirstSeen
        eidLastSeen
        namespace
        computerID
        systemUUID
        name
        domainName
        serialNumber
        manufacturer
        model
        ipAddress
        macAddresses
        isVirtual
        isEncrypted
        chassisType
        os {
          name
          language
        }
        services {
          status
          startupMode
        }
        installedApplications {
          uninstallable
          name
          version
          silentUninstallString
        }
        deployedSoftwarePackages {
          id
          name
          applicability
          gallery
        }
        compliance {
          cveFindings {
            cveYear
            summary
            severity
            cveId
            cvssScore
          }
          complianceFindings {
            standard
            standardVersion
            state
            id
            ruleId
          }
        }
      }
    }
  }
}

If this response size in bytes is too large, the response might include a ResourceExhausted error code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "errors": [
    {
      "message": "Error fetching endpoints: response error: rpc error: code = ResourceExhausted desc = grpc: received message larger than max (28156311 vs. 4194304)",
      "extensions": {
        "serviceName": "graphql-platform",
        "code": "DOWNSTREAM_SERVICE_ERROR"
      }
    }
  ],
  "data": {
    "endpoints": null
  }
}

Reduce the response size. You have the following options:

• Reduce the number of results returned per page.

• Reduce or otherwise constrain the information you request, especially if a given field might return an array for each result with multiple result values.

For the best results, due to the variability in size of Tanium deployments, retrieve 100 records per page as an initial test of your paginated query, and adjust the number of records returned per page based on performance and response time.

Uninstall API Gateway

If you need to uninstall API Gateway, perform the following steps.

Consult with Tanium Support before you uninstall or reinstall API Gateway.

The uninstall does not remove the API Gateway log from the Tanium Module Server. To remove the log after the uninstall completes, manually delete the \Program Files\Tanium\Tanium Module Server\services\gateway-files\ directory.

Contact Tanium Support

To contact Tanium Support for help, sign in to https://support.tanium.com.