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
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 @@
<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.
Copy link
Member

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

Check failure on line 102 in docs/source/schema-design/federated-schemas/reference/errors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/schema-design/federated-schemas/reference/errors.mdx#L102 

This fixes a grammatical error (using a possessive 's' for a plural noun) and replaces the passive voice ("are expected contain") with a more direct, active voice ("must contain").

```suggestion
selections must contain at least one of the following variables: <code>$args</code>, <code>$this</code>, or <code>$batch</code>.
```
Copy link
Member

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

Copy link
Member

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.

Check failure on line 131 in docs/source/schema-design/federated-schemas/reference/errors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/schema-design/federated-schemas/reference/errors.mdx#L131 

The original text is a sentence fragment. The suggestion is a complete, reader-centric sentence.

```suggestion
You can't use variables (such as <code>$this</code> or <code>$context</code>) to define connector <code>$batch</code> selections.
```
Batch selections should be mapped from the `$batch` variable.

Check warning on line 132 in docs/source/schema-design/federated-schemas/reference/errors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/schema-design/federated-schemas/reference/errors.mdx#L132 

Use "must" instead of "should" for a more authoritative tone when describing a requirement.

```suggestion
Batch selections must be mapped from the <code>$batch</code> variable.
```
Comment on lines +131 to +132
Copy link
Member

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

Check warning on line 147 in docs/source/schema-design/federated-schemas/reference/errors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/schema-design/federated-schemas/reference/errors.mdx#L147 

Complete sentences should end with punctuation.

```suggestion
<code>@connect</code> cannot be applied to a query, mutation, or subscription root type.
```
Copy link
Member

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 @@
</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).
Copy link
Member

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

Copy link
Member

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 @@
</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.

Check warning on line 175 in docs/source/schema-design/federated-schemas/reference/errors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/schema-design/federated-schemas/reference/errors.mdx#L175 

Use active voice ("Connectors don't support") instead of passive voice ("are not allowed") for a more direct and clear statement.

```suggestion
Connectors don't support [abstract types](/graphos/connectors/reference/limitations#abstract-schema-types-are-unsupported).
```

</td>
</tr>
Expand All @@ -111,7 +186,7 @@
</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.

Check warning on line 189 in docs/source/schema-design/federated-schemas/reference/errors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/schema-design/federated-schemas/reference/errors.mdx#L189 

Use active voice ("Connectors don't support") instead of passive voice ("are not allowed") for a more direct and clear statement.

```suggestion
Connectors don't support [certain directives](/graphos/connectors/reference/limitations).
```

</td>
</tr>
Expand Down Expand Up @@ -199,7 +274,7 @@
</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.

Check warning on line 277 in docs/source/schema-design/federated-schemas/reference/errors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/schema-design/federated-schemas/reference/errors.mdx#L277 

Use active, reader-centric voice ("you created") instead of passive voice ("were created") for a more direct tone.

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

</td>
</tr>
Expand Down Expand Up @@ -242,7 +317,7 @@
</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).

Check warning on line 320 in docs/source/schema-design/federated-schemas/reference/errors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/schema-design/federated-schemas/reference/errors.mdx#L320 

Use active, reader-centric voice ("You didn't provide") instead of passive voice ("was provided") for a more direct tone.

```suggestion
You didn't provide a <code>name</code> when creating a connector source with [<code>@source</code>](/graphos/connectors/requests#sharing-configuration-with-source).
```

</td>
</tr>
Expand Down Expand Up @@ -477,7 +552,7 @@
<tr>
<td>

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

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

Expand Down Expand Up @@ -512,7 +587,7 @@
</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 @@
</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.

Check warning on line 646 in docs/source/schema-design/federated-schemas/reference/errors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/schema-design/federated-schemas/reference/errors.mdx#L646 

Use active, reader-centric voice ("you provided") for a more direct and approachable tone.

```suggestion
The mapping you provided for <code>http.body</code> in <code>@connect</code> isn't valid. See [Mapping Language Reference](/graphos/connectors/mapping) for more information on writing mappings.
```

</td>
</tr>
Expand All @@ -582,7 +657,7 @@
</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.

Check warning on line 660 in docs/source/schema-design/federated-schemas/reference/errors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/schema-design/federated-schemas/reference/errors.mdx#L660 

Use active, reader-centric voice ("you provided") for a more direct and approachable tone.

```suggestion
A header you provided in <code>@source</code> or <code>@connect</code> isn't valid. See [Headers](/graphos/connectors/requests#headers) for more on connector request headers.
```

</td>
</tr>
Expand All @@ -596,7 +671,7 @@
</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.

Check failure on line 674 in docs/source/schema-design/federated-schemas/reference/errors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/schema-design/federated-schemas/reference/errors.mdx#L674 

This fixes the incorrect possessive grammar for a code element (`@connect`s) and uses active, reader-centric voice.

```suggestion
The selection mapping you provided in a <code>@connect</code> directive's <code>selection</code> isn't valid. See [Mapping Language Reference](/graphos/connectors/mapping) for more information on writing selection mappings.
```

</td>
</tr>
Expand All @@ -610,7 +685,7 @@
</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.

Check warning on line 688 in docs/source/schema-design/federated-schemas/reference/errors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/schema-design/federated-schemas/reference/errors.mdx#L688 

Use active, reader-centric voice ("you provided") for a more direct and approachable tone.

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

</td>
</tr>
Expand Down Expand Up @@ -918,7 +993,7 @@
</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.

Check warning on line 996 in docs/source/schema-design/federated-schemas/reference/errors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/schema-design/federated-schemas/reference/errors.mdx#L996 

Use active, reader-centric voice ("You defined") instead of passive voice ("was defined") and remove the unnecessary colon after "See".

```suggestion
You defined a <code>@key</code> without a corresponding entity connector. See [Working with Entities](/graphos/connectors/responses/entities) for more information.
```

</td>
</tr>
Expand All @@ -932,7 +1007,7 @@
</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 @@
</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.

Check warning on line 1024 in docs/source/schema-design/federated-schemas/reference/errors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/schema-design/federated-schemas/reference/errors.mdx#L1024 

Rephrasing the passive "is allowed" to the more direct "it can only have one" improves clarity.

```suggestion
The <code>@connect</code> directive has multiple [HTTP methods](/graphos/connectors/requests#http-methods) when it can only have one.
```

</td>
</tr>
Expand Down Expand Up @@ -1009,20 +1084,6 @@
<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 @@
</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).

Check warning on line 1528 in docs/source/schema-design/federated-schemas/reference/errors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/schema-design/federated-schemas/reference/errors.mdx#L1528 

Use active, reader-centric voice ("you created") instead of passive voice ("created with") for a more direct tone.

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

</td>
</tr>
Expand All @@ -1478,7 +1539,7 @@
</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 @@
</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.

Check warning on line 1600 in docs/source/schema-design/federated-schemas/reference/errors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/schema-design/federated-schemas/reference/errors.mdx#L1600 

Use active, reader-centric voice ("you haven't defined") instead of passive voice ("is not defined") for better clarity.

```suggestion
Part of the <code>@connect</code> directive refers to an [<code>$args</code>](/graphos/connectors/mapping/variables#args) variable that you haven't defined.
```

</td>
</tr>
Expand All @@ -1550,7 +1611,7 @@
</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.

Check warning on line 1614 in docs/source/schema-design/federated-schemas/reference/errors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/schema-design/federated-schemas/reference/errors.mdx#L1614 

The original phrasing is vague. The suggestion is more precise about why the error occurs, improving clarity.

```suggestion
The <code>@connect</code> directive refers to the [<code>$this</code>](/graphos/connectors/mapping/variables#this) variable in a context where it isn't defined.
```

</td>
</tr>
Expand Down Expand Up @@ -1634,7 +1695,7 @@
</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).

Check warning on line 1698 in docs/source/schema-design/federated-schemas/reference/errors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/schema-design/federated-schemas/reference/errors.mdx#L1698 

Use active voice for a more direct sentence. Replacing "i.e." with "such as" is more approachable.

```suggestion
A connector variable uses a type that is [not yet supported](/graphos/connectors/reference/limitations) (such as unions).
```

</td>
</tr>
Expand Down