Troubleshooting the Sitecore GraphQL API

Current version: 9.2

This topic describes some potential problems when using the Sitecore GraphQL API and suggests how to avoid these problems.

Testing multiple WebSocket connections on Windows 

IIS on a Windows desktop operating system (such as Windows 10 or Windows 8.1) has a hard limit of ten active connections. WebSocket connections count towards this and are persistent. If you have many open tabs with a socket connection to a desktop operating system, all requests to that IIS server can hang until a socket connection is closed (usually by closing the browser tab) to free up an available connection slot for an HTTP (or socket) connection to use. There is no workaround for this other than to avoid opening excessive numbers of sockets during testing.

Running queries over a WebSocket transport

You can run GraphQL queries (as opposed to subscriptions) over a WebSocket transport, but you can encounter problems using this technique while also depending on the Sitecore context. WebSocket queries and subscriptions execute on background threads, and they do not have access to Sitecore.Context.Database or Sitecore.Context.Site. This means that:

  • Context-aware GraphQL endpoints are unable to resolve the context database.

  • Item URLs resolved over a WebSocket connection are malformed due to the lack of a context site.

We suggest that you run queries over an HTTP connection and use WebSockets for subscriptions only. This ensures the best compatibility (towards firewalls that block sockets, for example) and makes it easier to debug (as socket debug tools are far less mature than HTTP tools).

Do you have some feedback for us?

If you have suggestions for improving this article,