Make protocol errors available in the error link #12281

jerelmiller · 2025-01-17T07:43:22Z

Makes protocol errors from multipart subscriptions available in the error link. Access it with the protocolErrors property:

const errorLink = onError(({ protocolErrors }) => {
  if (protocolErrors) {
    console.log(protocolErrors);
  }
});

changeset-bot · 2025-01-17T07:43:26Z

🦋 Changeset detected

Latest commit: e54cfda

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@apollo/client	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

svc-apollo-docs · 2025-01-17T07:43:27Z

✅ Docs preview ready

The preview is ready to be viewed. View the preview

File Changes

0 new, 1 changed, 0 removed

* (developer-tools)/react/(latest)/api/link/apollo-link-error.md

Build ID: b04d6bfd4e0ed73cab77de3e

URL: https://www.apollographql.com/docs/deploy-preview/b04d6bfd4e0ed73cab77de3e

pkg-pr-new · 2025-01-17T07:44:16Z

npm i https://pkg.pr.new/@apollo/client@12281

commit: e54cfda

github-actions · 2025-01-17T07:44:41Z

size-limit report 📦

Path	Size
dist/apollo-client.min.cjs	40.66 KB (0%)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/main.cjs"	50.07 KB (0%)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/main.cjs" (production)	47.18 KB (0%)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/index.js"	36.18 KB (0%)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/index.js" (production)	33.58 KB (0%)
import { ApolloProvider } from "dist/react/index.js"	1.26 KB (0%)
import { ApolloProvider } from "dist/react/index.js" (production)	1.24 KB (0%)
import { useQuery } from "dist/react/index.js"	5.21 KB (0%)
import { useQuery } from "dist/react/index.js" (production)	4.29 KB (0%)
import { useLazyQuery } from "dist/react/index.js"	5.7 KB (0%)
import { useLazyQuery } from "dist/react/index.js" (production)	4.78 KB (0%)
import { useMutation } from "dist/react/index.js"	3.62 KB (0%)
import { useMutation } from "dist/react/index.js" (production)	2.84 KB (0%)
import { useSubscription } from "dist/react/index.js"	4.42 KB (0%)
import { useSubscription } from "dist/react/index.js" (production)	3.48 KB (0%)
import { useSuspenseQuery } from "dist/react/index.js"	5.51 KB (0%)
import { useSuspenseQuery } from "dist/react/index.js" (production)	4.17 KB (0%)
import { useBackgroundQuery } from "dist/react/index.js"	5.01 KB (0%)
import { useBackgroundQuery } from "dist/react/index.js" (production)	3.66 KB (0%)
import { useLoadableQuery } from "dist/react/index.js"	5.09 KB (0%)
import { useLoadableQuery } from "dist/react/index.js" (production)	3.74 KB (0%)
import { useReadQuery } from "dist/react/index.js"	3.41 KB (0%)
import { useReadQuery } from "dist/react/index.js" (production)	3.35 KB (0%)
import { useFragment } from "dist/react/index.js"	2.36 KB (0%)
import { useFragment } from "dist/react/index.js" (production)	2.31 KB (0%)

netlify · 2025-01-17T07:45:18Z

✅ Deploy Preview for apollo-client-docs ready!

Name	Link
🔨 Latest commit	`e54cfda`
🔍 Latest deploy log	https://app.netlify.com/sites/apollo-client-docs/deploys/678a5f03c435e60008eb6fa4
😎 Deploy Preview	https://deploy-preview-12281--apollo-client-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

phryneas · 2025-01-17T10:31:05Z

src/link/error/index.ts

@@ -8,6 +16,10 @@ import { ApolloLink } from "../core/index.js";
 export interface ErrorResponse {
  graphQLErrors?: ReadonlyArray<GraphQLFormattedError>;
  networkError?: NetworkError;
+  protocolErrors?: ReadonlyArray<{


At this point, these errors become confusing without explanation or context.
What about some comments?

/** * Errors returned in the `errors` property of the GraphQL response. */ graphQLErrors?: ReadonlyArray<GraphQLFormattedError>; /** * Errors thrown during making a network request. * This is usually an error thrown during a `fetch` call or an error while * parsing the response from the network. */ networkError?: NetworkError; /** * Protocol errors. * This type of error occurs in follow-up responses of HTTP multipart * responses, e.g. if you are using `@defer` or Subscriptions via HTTP multipart. */

phryneas · 2025-01-17T10:31:54Z

src/link/error/index.ts

@@ -8,6 +16,10 @@ import { ApolloLink } from "../core/index.js";
 export interface ErrorResponse {
  graphQLErrors?: ReadonlyArray<GraphQLFormattedError>;
  networkError?: NetworkError;
+  protocolErrors?: ReadonlyArray<{


I know we call those "protocol errors" internally, but looking at when these actually occur (only on subsequent chunks of http multipart requests), could we maybe call this incrementalErrors instead?

Suggested change

protocolErrors?: ReadonlyArray<{

incrementalErrors?: ReadonlyArray<{

I named this protocolErrors to match the same property used in ApolloError where these specific types of errors are stored.

These errors aren't actually incremental errors but rather the transport-level errors sent from the router that occur when it can't communicate with the subgraph (i.e. the errors field next to payload, but not the errors field inside the payload property, which are just graphQLErrors).

phryneas · 2025-01-17T10:58:00Z

src/link/error/__tests__/index.ts

+      ]);
+    });
+
+    const mockLink = new ApolloLink((_operation) => {


This makes a lot of assumptions about what the HttpLink will do. I'll see if I can rewrite the test to use an actual HttpLink

phryneas · 2025-01-17T13:46:53Z

I've added tests actually using an HttpLink.

I had assumed that this would already also cover @defer, but it seems that's yet another blind spot.
I've added another test to document that blind spot.

phryneas · 2025-01-17T13:49:32Z

src/link/core/types.ts

@@ -53,7 +53,7 @@ export interface ApolloPayloadResult<
  payload: SingleExecutionResult | ExecutionPatchResult | null;
  // Transport layer errors (as distinct from GraphQL or NetworkErrors),
  // these are fatal errors that will include done: true.
-  errors?: ReadonlyArray<Error | string>;
+  errors?: ReadonlyArray<GraphQLFormattedError | string>;


Noticed this while writing the test - this is not a native Error object, but a JSON-parsed plain object with a message and potentially more fields. This type seems more fitting.

This makes sense. According to the protocol:

Both types of errors follow the GraphQL error format, but top-level errors never include locations or path.

This does make me question the string type here given that statement. I wonder if it would also make sense to add & { locations?: never; path?: never } to the type to make it even more accurate.

Yeah, admittedly, that string type seems kinda off.
As for the & { locations?: never; path?: never } - we could do that, but I wouldn't sweat it too much honestly - it's already optional, so nobody should be relying on those.

phryneas

Generally, I'd approve this PR, but I also want to suggest that we extend it to also handle @defer incremental errors and move both of those types of errors together under an incrementalErrors field.

Alternatively, we could keep this as "protocol errors" (but I'm not sure we use that name in any user-facing documentation) and expose @defer errors as graphQLErrors in a future PR.

phryneas · 2025-01-17T13:52:51Z

src/link/error/index.ts

+  protocolErrors?: ReadonlyArray<{
+    message: string;
+    extensions?: GraphQLErrorExtensions[];
+  }>;


This could also just be ReadonlyArray<GraphQLFormattedError>, or we adjust ApolloPayloadResult to have a type matching this.

I used the type defined in ApolloError for this. I figured they should match.

Hmm, maybe it might also make sense to just reference ApolloPayloadResult['errors'] to create a strong connection showing where this comes from?

jerelmiller · 2025-01-17T15:58:40Z

@phryneas to my knowledge, @defer is not supported with multipart subscriptions. We warn when trying to do both, hence why I didn't include any @defer specific tests in this PR. I appreciate the effort to include that here, but is it necessary right now?

jerelmiller · 2025-01-17T16:22:05Z

Discussed in person. We are going to pull the work for @defer errors not handled in error link to a separate followup PR.

jerelmiller added 3 commits January 17, 2025 00:15

Allow error link to handle protocol errors

445017e

Add test to ensure retry can happen after protocol errors

7b4338c

Add changeset

e51ef3e

jerelmiller requested a review from phryneas January 17, 2025 07:43

Add protocolErrors to docs

034dd47

jerelmiller requested a review from a team as a code owner January 17, 2025 07:46

phryneas reviewed Jan 17, 2025

View reviewed changes

add tests for incremental subscription & @defer with errorLink

e54cfda

phryneas reviewed Jan 17, 2025

View reviewed changes

phryneas approved these changes Jan 17, 2025

View reviewed changes

github-actions bot added the auto-cleanup 🤖 label Jan 17, 2025

phryneas reviewed Jan 17, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Make protocol errors available in the error link #12281

Make protocol errors available in the error link #12281

jerelmiller commented Jan 17, 2025

changeset-bot bot commented Jan 17, 2025 •

edited

Loading

svc-apollo-docs commented Jan 17, 2025 •

edited

Loading

pkg-pr-new bot commented Jan 17, 2025 •

edited

Loading

github-actions bot commented Jan 17, 2025 •

edited

Loading

netlify bot commented Jan 17, 2025 •

edited

Loading

phryneas Jan 17, 2025

phryneas Jan 17, 2025 •

edited

Loading

jerelmiller Jan 17, 2025

phryneas Jan 17, 2025

phryneas commented Jan 17, 2025

phryneas Jan 17, 2025

jerelmiller Jan 17, 2025

phryneas Jan 17, 2025

phryneas left a comment

phryneas Jan 17, 2025

jerelmiller Jan 17, 2025

phryneas Jan 17, 2025

jerelmiller commented Jan 17, 2025

jerelmiller commented Jan 17, 2025

	protocolErrors?: ReadonlyArray<{
	incrementalErrors?: ReadonlyArray<{

Make protocol errors available in the error link #12281

Are you sure you want to change the base?

Make protocol errors available in the error link #12281

Conversation

jerelmiller commented Jan 17, 2025

changeset-bot bot commented Jan 17, 2025 • edited Loading

🦋 Changeset detected

svc-apollo-docs commented Jan 17, 2025 • edited Loading

✅ Docs preview ready

pkg-pr-new bot commented Jan 17, 2025 • edited Loading

github-actions bot commented Jan 17, 2025 • edited Loading

size-limit report 📦

netlify bot commented Jan 17, 2025 • edited Loading

✅ Deploy Preview for apollo-client-docs ready!

Choose a reason for hiding this comment

phryneas Jan 17, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

phryneas commented Jan 17, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

phryneas left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jerelmiller commented Jan 17, 2025

jerelmiller commented Jan 17, 2025

changeset-bot bot commented Jan 17, 2025 •

edited

Loading

svc-apollo-docs commented Jan 17, 2025 •

edited

Loading

pkg-pr-new bot commented Jan 17, 2025 •

edited

Loading

github-actions bot commented Jan 17, 2025 •

edited

Loading

netlify bot commented Jan 17, 2025 •

edited

Loading

phryneas Jan 17, 2025 •

edited

Loading