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 constains 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.

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.