This chapter contains common troubleshooting steps. Additionally, there is a section for FAQs (Frequently Asked Questions) where you might find answers to your problems.

Debug Logging

For @neo4j/graphql

@neo4j/graphql uses the debug library for debug-level logging. You can turn on all debug logging by setting the environment variable DEBUG to @neo4j/graphql:* when running. For example:

DEBUG=@neo4j/graphql:* node src/index.js

Alternatively, if you are debugging a particular functionality, you can specify a number of namespaces to isolate certain log lines:

  1. @neo4j/graphql:* - Logs all

  2. @neo4j/graphql:auth - Logs the status of authorization header and token extraction, and decoding of JWT

  3. @neo4j/graphql:graphql - Logs the GraphQL query and variables

  4. @neo4j/graphql:execute - Logs the Cypher and Cypher paramaters before execution, and summary of execution

For @neo4j/introspector

@neo4j/introspector has its own debug logging namespace and you can turn on logging for it with:

DEBUG=@neo4j/introspector node src/index.js

Read more about the introspector.

Query Tuning

Hopefully you won’t need to perform any query tuning, but if you do, the Neo4j GraphQL Library allows you to set the full array of query options on construction of the library.

Please only set these options if you know what you are doing.

For example, in order to set the Cypher runtime to "interpreted":

const { Neo4jGraphQL, CypherRuntime } = require("@neo4j/graphql");
const neo4j = require("neo4j-driver");
const { ApolloServer } = require("apollo-server");

const typeDefs = `
    type Movie {
        title: String!

const driver = neo4j.driver(
    neo4j.auth.basic("neo4j", "password")

const neoSchema = new Neo4jGraphQL({
    config: {
        queryOptions: {
            runtime: CypherRuntime.INTERPRETED,

const server = new ApolloServer({
    schema: neoSchema.schema,
    context: ({ req }) => ({ req }),

server.listen().then(({ url }) => {
  console.log(`Server ready at ${url}`);