Skip to content

docs: Update connectors error codes #3260

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Hunter-apollo wants to merge 2 commits into
base: next
Choose a base branch
from
Open

docs: Update connectors error codes #3260

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
79bd405
Update Connectors error codes for 2.11 release.
Hunter-apollo May 28, 2025
b717d13
Address PR comments
Hunter-apollo Jun 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 95 additions & 34 deletions docs/source/schema-design/federated-schemas/reference/errors.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,14 +62,89 @@ A [circular reference](/graphos/schema-design/connectors/troubleshooting#circula
<tr>
<td>

##### `CONNECT_BATCH_AND_THIS`

Since v2.11.0<sup>\*\*</sup>

</td>
<td>

Using both [`$batch`](/graphos/connectors/mapping/variables#batch) and [`$this`](/graphos/connectors/mapping/variables#this) in a mapping is not allowed.

@dylan-apollo dylan-apollo Jul 1, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Using both [`$batch`](/graphos/connectors/mapping/variables#batch) and [`$this`](/graphos/connectors/mapping/variables#this) in a mapping is not allowed.
Using both [`$batch`](/graphos/connectors/mapping/variables#batch) and [`$this`](/graphos/connectors/mapping/variables#this) in the same connector is not allowed.


</td>
</tr>
<tr>
<td>

###### `CONNECTORS_BATCH_KEY_NOT_IN_SELECTION`

Since v2.11.0<sup>\*\*</sup>

</td>
<td>

Every field used on `$batch` must also appear in the `selection` of the same connector.
See [Rules for `batch` Connectors](/graphos/connectors/requests/batching#rules-for-batch-connectors) for more information.

</td>
</tr>
<tr>
<td>

###### `CONNECTORS_CANNOT_RESOLVE_KEY`

Since v2.11.0<sup>\*\*</sup>

</td>
<td>

A `@key` could not be resolved for the given combination of variables. In order to create a valid `@key`
selection's are expected contain at least one of the following variables: `$args`, `$this`, or `$batch`.

@dylan-apollo dylan-apollo Jul 1, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
selection's are expected contain at least one of the following variables: `$args`, `$this`, or `$batch`.
selections are expected contain at least one of the following variables: `$args`, `$this`, or `$batch`.

Librarian is correct

@dylan-apollo dylan-apollo Jul 1, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's totally unclear to me from reading the code how this actually happens 😅. Seems like the user actually only gets an error if they mention a field which doesn't exist... which also generates another duplicate error. But I don't think not mentioning any variables causes this? So maybe we should be getting rid of this error code long term.

It already exists in released routers now, though, so I guess we should leave it documented.


</td>
</tr>
<tr>
<td>

###### `CONNECTORS_FIELD_WITH_ARGUMENTS`

Since v2.10.0<sup>\*\*</sup>

</td>
<td>

A field resolved by a connector has arguments defined.
A field resolved by a [connector](/graphos/connectors) has arguments defined.

</td>
</tr>
<tr>
<td>

###### `CONNECTORS_NON_ROOT_BATCH_KEY`

Since v2.11.0<sup>\*\*</sup>


</td>
<td>

Variables (such as `$this` or `$context`) to define Connector `$batch` selections.
Batch selections should be mapped from the `$batch` variable.
Comment on lines +131 to +132

@dylan-apollo dylan-apollo Jul 1, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't even know why we have this restriction—that doesn't seem like it should be required? But I think we should spell out the issue more clearly:

Suggested change
Variables (such as `$this` or `$context`) to define Connector `$batch` selections.
Batch selections should be mapped from the `$batch` variable.
The `selection` fields which match any used `$batch` fields must come from the API response, not from any other variables.

Can you also add a good/bad to https://www.apollographql.com/docs/graphos/connectors/requests/batching#rules-for-batch-connectors that we can link to here? Unless I'm misunderstanding the code—but again, I'm not sure why we added this restriction? What if the ID comes back in a header for some reason?


</td>
</tr>
<tr>
<td>


###### `CONNECT_ON_ROOT`

Since v2.11.0<sup>\*\*</sup>

</td>
<td>

`@connect` cannot be applied to a query, mutation, or subscription root type

@dylan-apollo dylan-apollo Jul 1, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`@connect` cannot be applied to a query, mutation, or subscription root type
`@connect` cannot be applied to a query, mutation, or subscription root type.

For librarian


</td>
</tr>
Expand All @@ -83,7 +158,7 @@ Since v2.10.0<sup>\*\*</sup>
</td>
<td>

The schema includes fields that aren't resolved by a connector.
The schema includes fields that aren't resolved by a [connector](/graphos/connectors).

@dylan-apollo dylan-apollo Jul 1, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The schema includes fields that aren't resolved by a [connector](/graphos/connectors).
When using [Connectors](/graphos/connectors) in a schema, every field must be resolvable by at least one Connector. To solve this problem, you will need to either add a `@connect` to the field in question, or add the field to the `selection` of an existing `@connect`.

@dylan-apollo dylan-apollo Jul 1, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know you just added the link, but I figure we could explain the solution a bit while we're here.


</td>
</tr>
Expand All @@ -97,7 +172,7 @@ Since v2.10.0<sup>\*\*</sup>
</td>
<td>

[Abstract types](/graphos/schema-design/connectors/limitations#abstract-schema-types-are-unsupported) are not allowed when using connectors.
[Abstract types](/graphos/connectors/reference/limitations#abstract-schema-types-are-unsupported) are not allowed when using connectors.

</td>
</tr>
Expand All @@ -111,7 +186,7 @@ Since v2.10.0<sup>\*\*</sup>
</td>
<td>

[Certain directives](/graphos/schema-design/connectors/limitations) are not allowed when using connectors.
[Certain directives](/graphos/connectors/reference/limitations) are not allowed when using connectors.

</td>
</tr>
Expand Down Expand Up @@ -199,7 +274,7 @@ Since v2.10.0<sup>\*\*</sup>
</td>
<td>

Indicates two connector sources with the same name were created.
Indicates two connector [sources](/graphos/connectors/requests#sharing-configuration-with-source) with the same name were created.

</td>
</tr>
Expand Down Expand Up @@ -242,7 +317,7 @@ Since v2.10.0<sup>\*\*</sup>
</td>
<td>

No `name` was provided when creating a connector source with `@source`.
No `name` was provided when creating a connector source with [`@source`](/graphos/connectors/requests#sharing-configuration-with-source).

</td>
</tr>
Expand Down Expand Up @@ -477,7 +552,7 @@ Replaces [`VALUE_TYPE_FIELD_TYPE_MISMATCH`](#value-type-field-type-mismatch).
<tr>
<td>

###### `GRAPHQL_ERROR`
###### `GRAPH_QL_ERROR`

Since v2.10.0<sup>\*\*</sup>

Expand Down Expand Up @@ -512,7 +587,7 @@ Since v2.10.0<sup>\*\*</sup>
</td>
<td>

Fields that return an object type must use a group selection mapping `{}`.
Fields that return an object type must use a group selection mapping (i.e. `a { b }`).

</td>
</tr>
Expand Down Expand Up @@ -568,7 +643,7 @@ Since v2.10.0<sup>\*\*</sup>
</td>
<td>

The `http.body` provided in `@connect` was not valid.
The mapping for `http.body` provided in `@connect` was not valid. See [Mapping Language Reference](/graphos/connectors/mapping) for more information on writing mappings.

</td>
</tr>
Expand All @@ -582,7 +657,7 @@ Since v2.10.0<sup>\*\*</sup>
</td>
<td>

A provided header in `@source` or `@connect` was not valid.
A provided header in `@source` or `@connect` was not valid. See [Headers](/graphos/connectors/requests#headers) for more on connector request headers.

</td>
</tr>
Expand All @@ -596,7 +671,7 @@ Since v2.10.0<sup>\*\*</sup>
</td>
<td>

The provided selection mapping in a `@connect`s `selection` was not valid.
The provided selection mapping in a `@connect`s `selection` was not valid. See [Mapping Language Reference](/graphos/connectors/mapping) for more information on writing selection mappings.

</td>
</tr>
Expand All @@ -610,7 +685,7 @@ Since v2.10.0<sup>\*\*</sup>
</td>
<td>

The `name` provided for a `@source` was invalid. Source names must start with a letter, include only letters, numbers, underscores (`_`) and hyphens (`-`), and be less than 64 characters.
The `name` provided for a [`@source`](/graphos/connectors/requests#sharing-configuration-with-source) was invalid. Source names must start with a letter, include only letters, numbers, underscores (`_`) and hyphens (`-`), and be less than 64 characters.

</td>
</tr>
Expand Down Expand Up @@ -918,7 +993,7 @@ Since v2.10.0<sup>\*\*</sup>
</td>
<td>

A `@key` was defined without a corresponding entity connector.
A `@key` was defined without a corresponding entity connector. See: [Working with Entities](/graphos/connectors/responses/entities) for more information.

</td>
</tr>
Expand All @@ -932,7 +1007,7 @@ Since v2.10.0<sup>\*\*</sup>
</td>
<td>

The `@connect` directive is missing an HTTP method.
The `@connect` directive is missing an [HTTP method](/graphos/connectors/requests#http-methods).

</td>
</tr>
Expand All @@ -946,7 +1021,7 @@ Since v2.10.0<sup>\*\*</sup>
</td>
<td>

The `@connect` directive has multiple HTTP methods when only one is allowed.
The `@connect` directive has multiple [HTTP methods](/graphos/connectors/requests#http-methods) when only one is allowed.

</td>
</tr>
Expand Down Expand Up @@ -1009,20 +1084,6 @@ This is a specialization of [`SOURCE_NAME_MISMATCH`](#source_name_mismatch) erro
<tr>
<td>

###### `NULLABILITY_MISMATCH`

Since v2.10.0<sup>\*\*</sup>

</td>
<td>

A variable is nullable in a location which requires non-null at runtime.

</td>
</tr>
<tr>
<td>

###### `ONLY_INACCESSIBLE_CHILDREN`

Since v2.0.0
Expand Down Expand Up @@ -1464,7 +1525,7 @@ Since v2.10.0<sup>\*\*</sup>
</td>
<td>

The `source` argument used in a `@connect` directive doesn't match any named connecter sources created with `@source`.
The `source` argument used in a `@connect` directive doesn't match any named connector sources created with [`@source`](/graphos/connectors/requests#sharing-configuration-with-source).

</td>
</tr>
Expand All @@ -1478,7 +1539,7 @@ Since v2.10.0<sup>\*\*</sup>
</td>
<td>

Connectors currently [don't support subscription operations](/graphos/schema-design/connectors/limitations#subscriptions-are-unsupported).
Connectors currently [don't support subscription operations](/graphos/connectors/reference/limitations#subscriptions-are-unsupported).

</td>
</tr>
Expand Down Expand Up @@ -1536,7 +1597,7 @@ Since v2.10.0<sup>\*\*</sup>
</td>
<td>

Part of the `@connect` refers to an `$args` which is not defined.
Part of the `@connect` directive refers to an [`$args`](/graphos/connectors/mapping/variables#args) which is not defined.

</td>
</tr>
Expand All @@ -1550,7 +1611,7 @@ Since v2.10.0<sup>\*\*</sup>
</td>
<td>

Part of the `@connect` refers to an `$this` which is not defined.
Part of the `@connect` directive refers to an [`$this`](/graphos/connectors/mapping/variables#this) which is not defined.

</td>
</tr>
Expand Down Expand Up @@ -1634,7 +1695,7 @@ Since v2.10.0<sup>\*\*</sup>
</td>
<td>

A type used in a connector's variable is [not yet supported](/graphos/schema-design/connectors/limitations) (i.e., unions).
A type used in a connector's variable is [not yet supported](/graphos/connectors/reference/limitations) (i.e., unions).

</td>
</tr>
Expand Down