Why subscription example from the official docs is not working correctly?

Hi there,

I am reading the documentation about subscriptions, and it seems it’s just not working. The example you will see below is the example from the official documentation. (I am not able to run this with or without docker).

I got this error message:

Unable to reach subscription server

To diagnose the problem, please run: npx diagnose-endpoint@1.1.0 --endpoint=ws://localhost:3000/graphql

Here is my code:

import { createServer } from "http";
import express from "express";
import { ApolloServerPluginDrainHttpServer } from "apollo-server-core";
import { makeExecutableSchema } from "@graphql-tools/schema";
import { WebSocketServer } from "ws";
import { useServer } from "graphql-ws/lib/use/ws";
import { ApolloServer } from "apollo-server-express";
import DataLoader from "dataloader";

import { loadAuthors } from "./dataloaders";

const PORT = 3000;

import resolvers from "./resolvers";
import typeDefs from "./typedefs";

const main = async () => {
  const schema = makeExecutableSchema({ typeDefs, resolvers });
  const app = express();
  const httpServer = createServer(app);

  const wsServer = new WebSocketServer({
    server: httpServer,
    path: "/graphql",
  const serverCleanup = useServer({ schema }, wsServer);

  const context = {
    userId: 1,
    loaders: {
      authors: new DataLoader((keys: readonly string[]) => loadAuthors(keys)),

  const server = new ApolloServer({
    plugins: [
      // Proper shutdown for the HTTP server.
      ApolloServerPluginDrainHttpServer({ httpServer }),

      // Proper shutdown for the WebSocket server.
        async serverWillStart() {
          return {
            async drainServer() {
              await serverCleanup.dispose();
  await server.start();
  server.applyMiddleware({ app });

  // Now that our HTTP server is fully set up, actually listen.
  httpServer.listen(PORT, () => {
      `🚀 Query endpoint ready at http://localhost:${PORT}${server.graphqlPath}`,
      `🚀 Subscription endpoint ready at ws://localhost:${PORT}${server.graphqlPath}`,


Hello! This article has just been updated to use the graphql-ws subscription library instead of the unmaintained subscriptions-transport-ws library. Consequently, you need to make sure that whatever GraphQL client you’re using to send subscriptions is also using the same protocol. To confirm this for various clients, see this section.

Hope this helps!

Hi Stephen,

I am just using this official document. At some point, right below the text that says: " A completed example of setting up subscriptions is shown below: " you can expand and see the example. If I try running that example, it simply won’t connect displaying this error above.

What is the “it” that won’t connect? What client are you using?

Hi Glasser,

I am using the official one: Studio

What I am saying is literally if you run the official docs example, it doesn’t work.

Thanks for following up! Are you able to connect if you use the setting described here to switch the protocol Studio is using?

That actually worked. Thanks @StephenBarlow

1 Like

Great! Thanks for reporting, we’ll make this clearer in the Subscriptions doc.

Once I made subscriptions working on the API side and in the Playground by choosing the graphql-ws protocol, I have huge troubles setting up the Apollo Client to connect to this protocol.

According to the docs here, I should be able to connect to the Apollo client.

Additional piece of code is:

// ApolloClient and InMemoryCache are being imported from “@apollo/client”

export const apolloClient = new ApolloClient({
  link: splitLink,
  cache: new InMemoryCache(),

What should I change? It is very hard nowadays to catch up with all versioning of Apollo and usage. I think you should make one blog on how to do things right since you have changed a lot of things.

Apologies for the confusion, this update is still very fresh and we’re working out ways to clarify the transition.

To use the graphql-ws library for subscriptions in Apollo Client, you need to update to Apollo Client 3.5.10 or later. You then use the GraphQLWsLink as your subscriptions terminating link instead of WebSocketLink. See also the most recent version of the Apollo Client subscriptions article (it looks like you were viewing the v2 article).

For more information on minimum required library versions, please see this table.

Hello, I am also having an issue when following the v3 apollo documentation on subscriptions. I set up my server to use subscriptions using graphql-ws, but when I open the studio and try to run the subscription it simply won’t connect. I checked the settings and made sure that the studio’s connection settings are correct. When I run the subscription it looks like this…

Any help would be greatly appreciated!

Hello @pschlafley!

Could you please share a screenshot of your Studio Explorer connection settings? It seems like this might be an issue around configuring your Studio’s subscriptions endpoint and implementation, but seeing your current settings will confirm my suspicion!

As a side question, is your server logging any errors when trying to run your subscription operation?

Here are my studio settings, and no, my server isn’t logging any errors when I run the subscription… at the moment

Huh, that’s tricky. :thinking: Would it be possible to share your server code where you create the subscription server (and the ApolloServer and HTTP server instances)? It would also be helpful to see how you are resolving the subscription; if you could share your resolver?

Yep, here they are!

The first thing that comes to mind is that you’ll need your Subscription.newUserCreated's subscribe function to return the pubsub.asyncIterator (i.e., add a return to line 20 in your resolvers.js). It’s strange that you didn’t get a server error for that. Let me know if that works!

I added the return statement, still not working

Does the createUser mutation run as you expect it to? Does it create new users without issue? Sorry for all the questions, I’m just trying to get the full picture of your app’s behavior as it is now.