Last updated Dec 11, 2024

GraphQL Error Handling

When a Compass GraphQL query or mutation is executed, an error may be returned. This page explains what those errors mean.

Query errors

Query errors are typically returned inside the QueryError objects. For example:

1
2
{
  "data": {
    "compass": {
      "component": {
          "__typename": "QueryError",
          "message": "Component not found", // A developer readable error message. May change over time.
          "extensions": [
            {
              "statusCode": 404, // An HTTP status code representing the error
              "errorType": "COMPONENT_NOT_FOUND", // A code representing the error. This will not change over time.
            }
          ]
        }
      }
    }
  }
}

Mutation errors

Mutation errors are typically found in mutation payload objects. For example:

1
2
{
  "data": {
    "compass": {
      "updateComponent": {
        "__typename": "UpdateCompassComponentPayload",
        "success": false,
        "errors": [
          {
            "message": "The component’s Atlassian resource identifier (ARI) is invalid. Try again with a valid ARI.", // A developer readable error message. May change over time.
            "extensions": {
              "statusCode": 400, // An HTTP status code representing the error
              "errorType": "COMPONENT_ARI_INVALID" // A code representing the error. This will not change over time.
            }
          }
        ],
        "componentDetails": null
      }
    }
  }
}

Error types

The following error types may be returned by Compass queries and mutations.

Error type Description
ARGUMENT_INVALID An invalid argument was provided in a HTTP call
CLOUD_ID_INVALID The cloud ID does not exist
COMPASS_NOT_AVAILABLE Compass is not available on site with cloudId: cloudId
COMPONENT_ARI_INVALID The component’s Atlassian resource identifier (ARI) is invalid. Try again with a valid ARI.
COMPONENT_DESCRIPTION_TOO_LONG The component description is too long. It should be below 1000 characters
COMPONENT_FIELD_VALUE_CANNOT_BE_NULL The component field value is null. Provide a field value and try again.
COMPONENT_LINKS_MAXIMUM_PER_TYPE_REACHED The maximum number of component links for a link type has been reached
COMPONENT_LINK_DOES_NOT_EXIST Component link with ID [id] does not exist
COMPONENT_LINK_NAME_TOO_LONG The provided component link name is too long
COMPONENT_LINK_URL_NOT_A_VALID_URL The URL format of the component link is invalid. Try again with a link having a valid URL format.
COMPONENT_LINK_URL_TOO_LONG The provided component link url is too long
COMPONENT_NAME_BLANK The component name is blank. Provide a name and try again.
COMPONENT_NAME_TOO_LONG The component name is too long. Try again with a name shorter than 100 characters.
COMPONENT_NOT_FOUND The component requested for could not be found.
EXTERNAL_ALIAS_COULD_NOT_BE_CREATED We couldn't create the external alias. Either the alias is already associated with a component, or the limit of associated aliases for this component is already reached. Try creating a different alias or reduce the number of aliases associated with this component.
RELATIONSHIP_NOT_FOUND We couldn’t find a relationship for those component IDs. Try creating the relationship or use valid component IDs.
RELATIONSHIP_START_NODE_NOT_FOUND We couldn’t create this relationship because the component at the start node does not exist. Check for typos or try again with a different component
RELATIONSHIP_END_NODE_NOT_FOUND We couldn’t create this relationship because the component at the end node does not exist. Check for typos or try again with a different component.
RELATIONSHIP_ALREADY_EXISTS The relationship between these components already exists. Try creating a different relationship.
RELATIONSHIP_START_AND_END_NODES_MUST_BELONG_TO_THE_SAME_SITE We couldn’t create a relationship between these components because they belong to different Compass sites. Try again with components that belong to the same Compass site.
RELATIONSHIP_NODES_SELF_REFERENCING_ERROR We couldn't create this relationship because the start node component is the same as the end node component. Try again with different components.
RELATIONSHIP_START_NODE_ARI_INVALID The Atlassian resource identifier (ARI) of the component at the start node of this relationship is invalid. Try again with a valid ARI.
RELATIONSHIP_END_NODE_ARI_INVALID The Atlassian resource identifier (ARI) of the component at the end node of this relationship is invalid. Try again with a valid ARI.
CONSTRAINT_VIOLATION A validation constraint was violated
DUPLICATE_FIELD_DEFINITION_ID Field definition [definitionId] already exists. Try again with a different field definition ID.
EXTERNAL_ALIAS_NOT_FOUND We couldn’t find the external alias. Check for typos and try again.
FIELDS_NOT_SUPPORTED Currently, fields are supported only for components of the 'Service' type.
FIELD_CANNOT_BE_NULL A provided input field cannot be null
FIELD_DEFINITION_DOES_NOT_EXIST Field definition [definitionId] does not exist. Try again with a valid field definition for the component type.
FIELD_MISSING Field [fieldName] must not be null
FIELD_VALUE_DOES_NOT_MATCH_FIELD_DEFINITION The field value for field definition [definitionId] does not match its field type. Try again with a valid field value.
FIELD_VALUE_ELEMENT_IS_NOT_ALLOWED The field value element for field definition [definitionId] at index [index] is invalid. Try again with a valid field value element.
FIELD_VALUE_INVALID_NUMBER_OF_ELEMENTS The field value for field definition [definitionId] has an incorrect number of elements. Try again with the correct number of elements.
FORMAT_INVALID Error when parsing JSON
INTERNAL_SERVER_ERROR An internal error has occurred. If this persists, please contact our support.
INVALID_COMPASS_SITE_ID Invalid Compass Site ID found in headers. This mutation may only be called from a valid Forge app.
INVALID_COMPONENT_OWNER_FORMAT The format of the component owner value is invalid. Try again using the format of a team's Atlassian resource identifier (ARI).
INVALID_ECOSYSTEM_APP_ID Invalid ecosystem app ID found in headers. This mutation may only be called from a valid Forge app.
NUMBER_OF_ITEMS_REQUESTED_INVALID_EXCEPTION The number of items requested is invalid, must be between [min] to [max].
MISSING_CLOUD_ID Could not get cloud ID or hostname from request headers
MISSING_CLOUD_ID_AND_HOSTNAME Could not get cloud ID or hostname from request headers
MISSING_ECOSYSTEM_HEADERS Ecosystem headers not found. This mutation may only be called from a valid Forge app.
ONE_OF_DIRECTIVE_VALIDATION_ERROR Type is annotated with @oneOf. One and only one of the fields must be provided.
PERMISSION_DENIED User does not have permission to perform this action.
RELATIONSHIP_LIMIT_REACHED We couldn’t create this relationship. The number of relationships for either the start or end node component has reached its limit. Try creating a different relationship or reduce the number of relationships associated with the component.
REQUIRED_FIELD_VALUE_DOES_NOT_EXIST A field value for field definition [definitionId] is required. Provide a field value and try again.
SCORECARD_ARI_INVALID This is not a valid scorecard ARI
SCORECARD_COMPONENT_RELATIONSHIP_NOT_FOUND We couldn’t find a relationship for those scorecard and component IDs. Try applying the scorecard to the component or use valid IDs.
SCORECARD_CREATION_FAILED We couldn’t create your scorecard. Check your connection and try again.
SCORECARD_CRITERIA_ARE_REQUIRED We couldn’t create your scorecard because it doesn’t have any criteria selected. Select at least one criterion and try again.
SCORECARD_CRITERIA_NOT_UNIQUE We couldn't create or update your scorecard because a criterion is selected more than once. Select unique criteria and try again.
SCORECARD_CRITERIA_WEIGHT_INVALID The scorecard criteria weight is invalid. Try again with a value from 1 through 100, both inclusive.
SCORECARD_CRITERIA_WEIGHT_TOTAL_INVALID The scorecard criteria weight values do not add up to 100%. Adjust the weight values so that they add up to 100% and try again.
SCORECARD_DESCRIPTION_BLANK The scorecard description is blank. Provide a description and try again.
SCORECARD_DESCRIPTION_TOO_LONG The scorecard description is too long. Try again with a description having a length shorter than or equal to 330 characters.
SCORECARD_NAME_BLANK The scorecard name is blank. Provide a name and try again.
SCORECARD_NAME_NOT_UNIQUE A scorecard with this name already exists. Try again with a different name.
SCORECARD_NAME_TOO_LONG The scorecard name is too long. Try again with a name having a length shorter than or equal to 40 characters.
SCORECARD_NOT_FOUND We couldn’t find your scorecard. Check for typos or try again with a different scorecard name.
SCORECARD_REQUIRED_IMPORTANCE_MUST_HAVE_ADMIN_PERM We couldn’t create or update your scorecard. The owner of a scorecard with ‘Required’ importance must be an administrator. Try again with a different owner.
SCORECARD_COMPONENT_RELATIONSHIP_LIMIT_REACHED We couldn’t assign scorecard to component because the scorecard is already assigned to the component. The number of relationships for either the scorecard or component has reached its limit.
SCORECARD_COMPONENT_RELATIONSHIP_SCORECARD_NOT_FOUND We couldn’t assign scorecard to component because the scorecard does not exist.
SCORECARD_COMPONENT_RELATIONSHIP_COMPONENT_NOT_FOUND We couldn’t assign scorecard to component because the component does not exist.
SCORECARD_ALREADY_APPLIED_TO_COMPONENT We couldn’t assign scorecard to component because the scorecard is already assigned to the component.
SCORECARD_NOT_ASSIGNABLE_ERROR We couldn’t assign scorecard to component because the scorecard is not assignable. Either it's a required scorecard or the componentType doesn't match the type of component
STORE_CONFLICT_EXCEPTION There was a problem saving your data, please try again some time later.
EXTERNAL_ALIAS_ID_CANNOT_BE_EMPTY The external alias ID is null. Provide a value for the ID and try again.
EXTERNAL_ALIAS_SOURCE_TOO_LONG External alias source has exceeded the maximum length of 1024
EXTERNAL_ALIAS_ID_TOO_LONG External alias ID has exceeded the maximum length of 1024
COMPONENT_LINK_TYPE_CANNOT_BE_ON_CALL Only Components of type Service can have an On Call link type. Please change your Component type and try again.
CAMPAIGN_CREATION_FAILED We couldn’t create your campaign. Check your connection and try again.
CAMPAIGN_NOT_FOUND We could not find your campaign. Check for typos or try again with a different campaign Id.
CAMPAIGN_UPDATE_FAILED We could not update your campaign. Please try again later.

Rate this page: