GraphQL Content API (2024)

COLLIDING_TYPE_NAMES

The COLLIDING_TYPE_NAMES error is returned when one or more content type IDs are converted to the same GraphQL type name. For more information about this error, see the Colliding type names section.

Example

 errors: [{ message: "Schema generation failed. Type name generated for the content types 'A_car', 'a_car_' would be the same for all of them: 'ACar'", extensions: { contentful: { code: 'COLLIDING_TYPE_NAMES', details: { collidingContentTypeIds: ['A_car', 'a_car_'], resultingTypeName: 'ACar', }, documentationUrl: ‘xxxxxx/colliding-type-names requestId: 'xxx' } } }]}

Solution

To prevent this error, make sure the content type IDs in your space environment cannot result in the same GraphQL type name. You can either enter two unique random IDs in the creation phase, or provide two distinct names that wouldn’t be converted to the same ID or GraphQL type name later on.For more information on how schemas and the type names are generated for your GraphQL schema, see the Schema generation section.

To fix this error, recreate one of the content types that have colliding IDs, making sure the new ID won’t collide with the second content type ID. You can also use the scripted approach described in the Scripting migrations with the Contentful CLI guide.

COLLIDING_TYPE_NAMES during query execution

We dynamically create the types for GraphQL values based off of their names. As a result, users can inadvertently create naming collisions.

The following example is a common scenario of how a naming collision can occur:

1. Create the following content types: BlogPost, BlogPostContent and BlogPostMoreContent.
2. Add a reference field called content to your BlogPost content type, and allow it to link to BlogPostContent and BlogPostMoreContent.
3. Create an entry of type BlogPost with its content field linking to an entry of type BlogPostMoreContent.
4. Query the BlogPost entry including the linked entry. A generic error message is returned expecting only entries of type BlogPostContent instead of BlogPostMoreContent.

Here is a breakdwon of what is actually happening:

When generating a BlogPostContent, we create an API-wide collection called BlogPostContentCollection for querying purposes. However, when generating the content field on a BlogPost, we also need to create a collection to enable querying. Unfortunately, this creates a name collision issue as both collections have the same name, but different types.This conflict can cause various issues in the codebase. In some cases, we are able to prevent schema generation. However, sometimes this occurs at query execution.To fix this, determine what fields are causing a collision and rename one of the conflicting fields.

COLLIDING_FIELD_NAMES

The COLLIDING_FIELD_NAMES error is returned when several field IDs from the same content type are transformed into the same GraphQL field name.

Example

 errors: [ { message: "Schema generation failed. Field name 'firstName' generated for the field 'first_name' in the content type 'brand' collides with an already existing field.", extensions: { contentful: { code: "COLLIDING_FIELD_NAMES", details: { fieldApiName: "first_name", contentTypeId: "brand", fieldName: "firstName" }, documentationUrl: ‘xxxxxx/colliding-field-names requestId: 'xxx' } } } ]}

Solution

To prevent this error, make sure the field IDs you’re using on each content type cannot result in the same GraphQL field name.To fix this error, change the ID of one of the colliding fields in question using the web app or the Content Management API.

RESERVED_FIELD_NAME

The RESERVED_FIELD_NAME error is returned when a field ID is transformed into a reserved GraphQL field name. Reserved field names are sys, linkedFrom and contentfulMetadata.

Example

 errors: [{ message: "Schema generation failed. Field name 'linkedFrom' generated for the field 'linked_from' in the content type 'blog' is reserved.", extensions: { contentful: { code: 'RESERVED_FIELD_NAME', details: { contentTypeId: 'blog', fieldId: 'sys' }, documentationUrl: ‘xxxxxx/reserved-field-names' requestId: 'xxx' } } }]}

Solution

To fix this error, change the field ID to a value that does not collide with any of the reserved names using the web app or the Content Management API.

UNKNOWN_ENVIRONMENT

The UNKNOWN_ENVIRONMNET error is returned when the requested environment does not exist or when the provided authentication token does not allow access to the specified environment.

Example

 errors: [{ message: 'Query cannot be executed. Requested environment does not exist in the space', extensions: { contentful: { code: 'UNKNOWN_ENVIRONMENT', details: { availableEnvironments: ['master', 'qa'] }, documentationUrl: ‘xxxxxx/unknown-environment' requestId: 'xxx' } } }] }

Solution

To fix this error you can:

• request an environment from the list of environments that are already enabled for your content delivery token, or

• adjust the token so that it has access to the environment you want to use in your query.

For more information on how authentication to the Content Delivery API and Content Preview API works and how you can configure them, see the Authentication section of the API reference.

UNKNOWN_SPACE

The UNKNOWN_SPACE error is returned when the space ID included in the URL is incorrect.

Example

 errors: [{ message: 'Query cannot be executed. The space could not be found.', extensions: { contentful: { code: 'UNKNOWN_SPACE', details: { message: 'Check if the space id in the URL is correct.' }, documentationUrl: ‘xxxxxx/unknown-space' requestId: 'xxx' } } }] }

Solution

To fix this error you can:

• request an environment from the list of environments that are already enabled for your content delivery token, or
• adjust the token so that it has access to the environment you want to use in your query.

For more information on how authentication to the Content Delivery API and Content Preview API works and how you can configure them, see the Authentication section of the API reference.

MISSING_QUERY

The MISSING_QUERY error is returned when the POST request does not contain a payload or when the GET request does not contain the following query parameter: query.

Example

 errors: [{ message: 'Query cannot be executed. The request does not include a query neither in the body nor in the query string', extensions: { contentful: { code: 'MISSING_QUERY', documentationUrl: ‘xxxxxx/missing-query' requestId: 'xxx' } } }] }

Solution

To fix this error, include a query in the body of a POST request or a query query parameter in the GET request.

QUERY_TOO_BIG

The QUERY_TOO_BIG error is returned when the query exceeds the maximum allowed size.

Example

 errors: [{ message: `Query cannot be executed. The maximum allowed size for a query is XXX bytes but it was YYY bytes`, extensions: { contentful: { code: 'QUERY_TOO_BIG', documentationUrl: ‘xxxxxx/query-too-big' querySizeInBytes: XXX, requestId: 'xxx' } } }]}

Solution

To fix this error, divide the query into smaller parts to get the information you need in multiple smaller queries.

INVALID_QUERY_FORMAT

The INVALID_QUERY_FORMAT error is returned when the query is not of type string.

Example

 errors: [{ message: "Query cannot be executed. The query is not a string", extensions: { contentful: { code: 'INVALID_QUERY_FORMAT', documentationUrl: ‘xxxxxx/invalid-query-format' requestId: 'xxx' } } }]}

Solution

To fix this error, make sure the query passed in the request is of type string.

INVALID_VARIABLES_FORMAT

The INVALID_VARIABLES_FORMAT error is returned when the variables included in the request are not a valid JSON object.

Example

 errors: [{ message: "Query cannot be executed. The request variables are not a JSON object", extensions: { contentful: { code: 'INVALID_VARIABLES_FORMAT', documentationUrl: ‘xxxxxx/invalid-variables-format' requestId: 'xxx' } } }]}

Solution

To fix this error, check the integrity of the variables sent and make sure the JSON object is valid.

PersistedQueryNotFound

The PersistedQueryNotFound error is returned when you send a hash for a query that is not cached in our server.

Example

 errors: [{ message: "PersistedQueryNotFound", extensions: { contentful: { code: 'PERSISTED_QUERY_NOT_FOUND', documentationUrl: ‘xxxxxx/persisted-query-not-found' requestId: 'xxx' } } }]}

Solution

To fix this error, make sure you cached the query first by sending the hash and the query in a previous request.

PersistedQueryMismatch

The PersistedQueryMismatch error is returned when the sha256Hash does not match the expected query hash.

Example

 errors: [{ message: "PersistedQueryMismatch", extensions: { contentful: { code: 'PERSISTED_QUERY_MISMATCH', documentationUrl: ‘xxxxxx/persisted-query-mismatch' requestId: 'xxx' } } }]}

Solution

To fix this error, make sure you hashed the query using the sha256Hash algorithm.

TOO_COMPLEX_QUERY

Disclaimer:The default complexity limit for collections is 100. The query complexity is calculated as the maximum number of entries and assets a query can potentially return.

The TOO_COMPLEX_QUERY error is returned when the calculated query complexity exceeds the maximum complexity allowed.

Example

 errors: [{ message: `Query cannot be executed. The maximum allowed complexity for a query is 10000 but it was 20000. Simplify the query e.g. by setting lower limits for collections.`, extensions: { contentful: { code: 'TOO_COMPLEX_QUERY', details: { cost: 10000, maximumCost: 20000 }, documentationUrl: ‘xxxxxx/too-complex-query’ requestId: 'xxx' } } }] }

Solution

To avoid this issue, simplify the query complexity by setting a lower limit in the GraphQL query. You can also limit the depth of the query. For reference fields, it’s recommended to set a limit on the number of allowed links in the content modeling section. If there is a lower number than the default 1000, it will be used to calculate the overall complexity instead.

Examples of actions to optimize a query

• Make sure all the collections queried have a limit set on them:

query {
 lessonCollection {
 items {
 title
 }
 }
}

query {
 lessonCollection(limit: 20) {
 items {
 title
 }
 }
}

• Lower the limits on nested collections in the query to significantly lower the resulting cost:

query {
 lessonCollection(limit: 200) {
 items {
 title
 imageCollection {
 title
 url
 }
 }
 }
}

query {
 lessonCollection(limit: 20) {
 items {
 title
 imageCollection(limit: 10) {
 title
 url
 }
 }
 }
}

• If you know how many entries can be in a specific collection, set the limit to that number or lower:

query {
 lessonCollection(limit: 200) {
 items {
 title
 imageCollection(limit: 100) {
 title
 url
 }
 }
 }
}
# if imageCollection contains only 50 entries
# then it’s better to lower the limit to 50.

query {
 lessonCollection(limit: 200) {
 items {
 title
 imageCollection(limit: 50) {
 title
 url
 }
 }
 }
}

• If you have the linkedFrom field and you know the exact number of entries you are linking to, set the limit to that number:

query {
 catCollection(limit: 20) {
 items {
 name
 linkedFrom {
 entryCollection {
 items {
 ... on FriendlyUser {
 firstName
 }
 }
 }
 }
 }
 }
}
# if you know that the number
# of entries linked from is 5
# set the limit to 5

query {
 catCollection(limit: 20) {
 items {
 name
 linkedFrom {
 entryCollection(limit: 5) {
 items {
 ... on FriendlyUser {
 firstName
 }
 }
 }
 }
 }
 }
}

• If the query is too deep, fetch the IDs of a nested collection and use a separate query for that collection:

query {
 lessonCollection(limit: 200) {
 items {
 title
 teacher {
 name
 primaryLessonsCollection(limit: 100) {
 items {
 title
 }
 }
 }
 }
 }
}

query {
 lessonCollection(limit: 200) {
 items {
 title
 teacher {
 sys {
 id
 }
 }
 }
 }
}

query($teacherIds: [String]) {
 teacherCollection(where: {
 sys: { id_in: $teacherIds } }
 ) {
 items {
 name
 primaryLessonsCollection(limit: 100) {
 items {
 title
 }
 }
 }
 }
}

QUERY_OPERATION_NAME_MISMATCH

The QUERY_OPERATION_NAME_MISMATCH error is returned when a GraphQL request is received without a valid or matching operation name. The server cannot determine which operation to execute based on the provided operation name.The error message includes the received operation name and the available operation names found in the query.

Example

 "errors": [ { "message": "Could not determine what operation to execute, received 'blogPostCollectionQuery3' but found 'blogPostCollectionQuery1, blogPostCollectionQuery2'", "extensions": { "contentful": { "code": "QUERY_OPERATION_NAME_MISMATCH", "requestId": "xxx" } } } ]}

Possible Causes:

• The operation name provided in the GraphQL request does not match any of the operation names defined in the query.
• The GraphQL query does not contain any operation names.

Solution

• Ensure that the operation name provided in the request is spelled correctly and matches one of the operation names defined in the query.
• If the GraphQL query does not contain any operation names, make sure to include the operation name when sending the request.

UNKNOWN_LOCALE

The UNKNOWN_LOCALE error is returned when the requested locale does not exist.

Example

 data: { pet: null }, errors: [{ message: "Query execution error. Requested locale 'de-DE' does not exist in the space", locations: [{ line: 0, column: 0 }], path: ['pet'], extensions: { contentful: { code: 'UNKNOWN_LOCALE', details: { availableLocaleCodes: ['en-US', 'es-ES'] }, documentationUrl: ‘xxxxxx/unknown-locale' requestId: 'xxx' } } }] }

Solution

To fix this error, request one of the available locale codes returned in the error details. For more information about editing a locale, see the Localization with Contentful tutorial.

UNRESOLVABLE_LINK

The UNRESOLVABLE_LINK error is returned when a link cannot be resolved because the target entity does not exist or it is not published.

NOTES:

• When a link cannot be resolved, a null value is returned on that field.

• When a link in an array cannot be resolved, a null value on its position is returned.

• For each link that cannot be resolved, an error object with the details is sent with the response.

To distinguish between single entity links and array links, pay attention to the type in the GraphQL schema and the actual GraphQL response.

Examples

{ data: { pet: null }, errors: [{ message: "Query execution error. Link to entry 'my-dog' on field 'pet' within type 'Blog' cannot be resolved", locations: [{line: x, column: y}], // whatever path: ['pet'], extensions: { contentful: { code: 'UNRESOLVABLE_LINK', details: { type: 'FriendlyUser', field: 'pet', linkType: 'entry', linkId: 'my-dog' }, documentationUrl: ‘xxxxxx/unresolvable-link', requestId: 'xxx' } } }]}// Array link// Note that we return one error per unresolvable link, almost identical, except by the `path`{ data: { pets: [ { name: 'fido' }, null, { name: 'scuby' }, null ] }, errors: [{ message: "Query execution error. Link to entry 'my-dog' on field 'pets' within type 'Blog' cannot be resolved", locations: [{line: x, column: y}], // whatever path: ['pets', 1], extensions: { contentful: { code: 'UNRESOLVABLE_LINK', details: { type: 'FriendlyUser', field: 'pets', linkType: 'entry', linkId: 'my-dog' }, documentationUrl: ‘xxxxxx/unresolvable-link', requestId: 'xxx' } } }, { message: "Query execution error. Link to entry 'my-dog' on field 'pets' within type 'Blog' cannot be resolved", locations: [{line: x, column: y}], // whatever path: ['pets', 2], extensions: { contentful: { code: 'UNRESOLVABLE_LINK', details: { type: 'FriendlyUser', field: 'pets', linkType: 'entry', linkId: 'my-dog' }, documentationUrl: ‘xxxxxx/unresolvable-link', requestId: 'xxx' } } }]}

Solution

To fix this error, adjust your query to only request entities that exist and are published. Additionally, you can handle this specific error gracefully in your application.

Skip unresolvable links

You can skip over unresolvable links by filtering where the sys.id_exists is true.

NOTE: To use the filter, you must have a validation rule set on the many reference field that makes it only accept one content type.

query { friendlyUserCollection { items { firstName catCollection(limit: 100, where:{sys:{id_exists:true}}) { items { name } } } }}

UNEXPECTED_LINKED_CONTENT_TYPE

The UNEXPECTED_LINKED_CONTENT_TYPE error is returned when the linked entry has an unexpected content type linked to it in the validations. This happens when a validation in a field is changed to disallow a specific content type that was previously allowed, while entries with links to that content type still exist.

Example

 { message: "Query execution error. Link from entry 'blog-1' to entry 'Tom' on field 'externalAuthor' within type 'Blog' returned an unexpected content type", locations: [{ line: 4, column: 13 }], path: ['blog', 'externalAuthor'], extensions: { contentful: { code: 'UNEXPECTED_LINKED_CONTENT_TYPE', details: { type: 'Blog', field: 'externalAuthor', entryId: 'Tom', contentType: 'person', permittedContentTypes: ['someOtherContentType'], linkingEntryId: 'blog-1', }, documentationUrl: ‘xxxxxx/unexpected-linked-content-type', requestId: someRequestId, }, }, }, ]

Solution

To fix this error, you can remove the links to entries to content types that aren’t allowed anymore, or adjust the allowed content types in the linked entry.

RESOURCES_EXHAUSTED

The RESOURCES_EXHAUSTED error is returned when the GraphQL query has used more resources for its execution than allowed.

Example

 data: { too: { name: 'Josh', age: 22, many: { db_ops: null, } } }, errors: [{ message: 'Query execution error. Query too complex to be executed in allocated resources', locations: [{ line: 4, column: 17 }], // Whatever path: ['too', 'many', 'db_ops'], extensions: { contentful: { code: 'RESOURCES_EXHAUSTED', documentationUrl: ‘xxxxxx/unresolvable-link', requestId: 'xxx' } } }]}

Solution

To fix this error, split the query into multiple simple queries.

UNRESOLVABLE_RESOURCE_LINK

The UNRESOLVABLE_RESOURCE_LINK error is returned when an External references or Functions query fails.

Example

 { "message": "Query execution error. 'vendorId' link cannot be resolved", "extensions": { "contentful": { "code": "UNRESOLVABLE_RESOURCE_LINK", "documentationUrl": "xxxxxx/unresolvable-resource-link", "requestId": "xxx", "details": { "app": "vendorId" } } }, "locations": [ { "line": 4, "column": 17 } ], "path": ["contentTypeId", "fieldId"] }]

Solution

To fix this error, you need to check your Third party data query and your entry that is linked to your app.