{"record":{"id":"5a2d3ef311b08e50","repo":"dgraph-io/dgraph","slug":"failed-to-lazy-load-graphql-schema","errorCode":null,"errorMessage":"failed to lazy-load GraphQL schema","messagePattern":"failed to lazy-load GraphQL schema","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"graphql/admin/admin.go","lineNumber":1019,"sourceCode":"\n\tresolvers := resolve.New(gqlSchema, resolverFactory)\n\tas.gqlServer.Set(ns, as.getGlobalEpoch(ns), resolvers)\n\n\t// reset status to up, as now we are serving the new schema\n\tmainHealthStore.up()\n}\n\nfunc (as *adminServer) lazyLoadSchema(namespace uint64) error {\n\t// if the schema is already in memory, no need to fetch it from disk\n\tif currentSchema, ok := as.gqlSchemas.GetCurrent(namespace); ok && currentSchema.Loaded {\n\t\treturn nil\n\t}\n\n\t// otherwise, fetch the schema from disk\n\tsch, err := getCurrentGraphQLSchema(namespace)\n\tif err != nil {\n\t\tglog.Errorf(\"namespace: %d. Error reading GraphQL schema: %s.\", namespace, err)\n\t\treturn errors.Wrap(err, \"failed to lazy-load GraphQL schema\")\n\t}\n\n\tvar generatedSchema schema.Schema\n\tif sch.Schema == \"\" {\n\t\t// if there was no schema stored in Dgraph, we still need to attach resolvers to the main\n\t\t// graphql server which should just return errors for any incoming request.\n\t\t// generatedSchema will be nil in this case\n\t\tglog.Infof(\"namespace: %d. No GraphQL schema in Dgraph; serving empty GraphQL API\",\n\t\t\tnamespace)\n\t} else {\n\t\tgeneratedSchema, err = generateGQLSchema(sch, namespace)\n\t\tif err != nil {\n\t\t\tglog.Errorf(\"namespace: %d. Error processing GraphQL schema: %s.\", namespace, err)\n\t\t\treturn errors.Wrap(err, \"failed to lazy-load GraphQL schema\")\n\t\t}\n\t}\n\n\tas.mux.Lock()","sourceCodeStart":1001,"sourceCodeEnd":1037,"githubUrl":"https://github.com/dgraph-io/dgraph/blob/759e242be62c91f8d084da06ad0c8d21256d9c07/graphql/admin/admin.go#L1001-L1037","documentation":"lazyLoadSchema fetches the stored GraphQL schema from Dgraph via getCurrentGraphQLSchema and wraps any failure (network/storage error reading the schema) with this message. The GraphQL server for the namespace cannot be constructed without the stored schema.","triggerScenarios":"First request hitting a namespace's GraphQL endpoint triggers lazy load, and reading dgraph.graphql.schema from Dgraph fails (connection error, timeout, internal Dgraph error).","commonSituations":"Dgraph backend unhealthy/overloaded at first request; ACL/permission issues reading the schema node; network partition between the GraphQL layer and the Dgraph storage backend.","solutions":["Retry the request — lazy loading is attempted per request and may succeed once the backend recovers.","Check the underlying error in the log line 'Error reading GraphQL schema' for the root cause.","Verify Dgraph health and that the client can read dgraph.graphql.schema (ACL permissions)."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// probe Dgraph health before first GraphQL request\nconst healthy = await fetch('/health').then(r => r.ok).catch(() => false);\nif (!healthy) await waitForHealthy();","typeGuard":null,"tryCatchPattern":"try { await graphqlQuery(q); } catch (e) { if (String(e).includes('failed to lazy-load GraphQL schema')) { await backoffRetry(() => graphqlQuery(q)); } else throw e; }","preventionTips":["Delay traffic until Dgraph storage backend is healthy","Monitor 'Error reading GraphQL schema' log lines","Check ACL permissions for reading dgraph.graphql.schema"],"tags":["graphql","lazy-load","storage","network"],"backgroundTag":"schema-load-failed","analyzedSha":"759e242be62c91f8d084da06ad0c8d21256d9c07","analyzedAt":"2026-09-01T14:42:12.034Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}