dgraph-io/dgraph · warning

Unavailable: Server not ready.

Error message

Unavailable: Server not ready.

What it means

The admin GraphQL server registers placeholder resolvers that return errMsgServerNotReady until the admin schema has been loaded from storage. Any query hitting a not-yet-registered field (here the getGQLSchema query) is answered with this Unavailable error instead of executing. It signals the server is up but the admin GraphQL layer is not initialized yet.

Source

Thrown at graphql/admin/admin.go:769

		WithQueryResolver("health", func(q schema.Query) resolve.QueryResolver {
			return resolve.QueryResolverFunc(resolveHealth)
		}).
		WithQueryResolver("state", func(q schema.Query) resolve.QueryResolver {
			return resolve.QueryResolverFunc(resolveState)
		}).
		WithQueryResolver("config", func(q schema.Query) resolve.QueryResolver {
			return resolve.QueryResolverFunc(resolveGetConfig)
		}).
		WithQueryResolver("listBackups", func(q schema.Query) resolve.QueryResolver {
			return resolve.QueryResolverFunc(resolveListBackups)
		}).
		WithQueryResolver("task", func(q schema.Query) resolve.QueryResolver {
			return resolve.QueryResolverFunc(resolveTask)
		}).
		WithQueryResolver("getGQLSchema", func(q schema.Query) resolve.QueryResolver {
			return resolve.QueryResolverFunc(
				func(ctx context.Context, query schema.Query) *resolve.Resolved {
					return &resolve.Resolved{Err: errors.Errorf(errMsgServerNotReady), Field: q}
				})
		}).
		WithMutationResolver("updateGQLSchema", func(m schema.Mutation) resolve.MutationResolver {
			return resolve.MutationResolverFunc(
				func(ctx context.Context, m schema.Mutation) (*resolve.Resolved, bool) {
					return &resolve.Resolved{Err: errors.Errorf(errMsgServerNotReady), Field: m},
						false
				})
		})
	for gqlMut, resolver := range adminMutationResolvers {
		// gotta force go to evaluate the right function at each loop iteration
		// otherwise you get variable capture issues
		func(f resolve.MutationResolver) {
			rf.WithMutationResolver(gqlMut, func(m schema.Mutation) resolve.MutationResolver {
				return f
			})
		}(resolver)
	}

View on GitHub (pinned to 759e242be6)

Solutions

1. Wait for the server to report ready (or retry the query with backoff) before calling getGQLSchema.
2. Check that the GraphQL schema stored in Dgraph (for the namespace) is intact so lazy loading completes.
3. If it persists after startup, inspect logs for errors in lazyLoadSchema/getCurrentGraphQLSchema that blocked schema registration.

Example fix

// before: curl /admin immediately after start
curl -X POST localhost:8080/admin -d '{getGQLSchema{schema}}'
// after: retry until ready
until curl -sf -X POST localhost:8080/admin -d '{__typename}' ; do sleep 1; done
curl -X POST localhost:8080/admin -d '{getGQLSchema{schema}}'

// wait until admin endpoint responds before real queries
async function adminReady(url) {
  for (let i = 0; i < 30; i++) {
    try { const r = await fetch(url, {method:'POST', body:'{__typename}', headers:{'Content-Type':'application/graphql'}}); if (r.ok) return true; } catch {}
    await new Promise(r => setTimeout(r, 1000));
  }
  return false;
}

try { await runAdminQuery(); } catch (e) { if (String(e).includes('Server not ready')) { await sleep(1000); /* retry */ } else throw e; }

When it happens

Trigger: Sending a GraphQL getGQLSchema query to the /admin endpoint before resetSchema/NewServers has finished loading the stored admin schema, i.e. during Dgraph startup or while a schema reset is in flight.

Common situations: Health probes or automation scripts hitting /admin immediately after process start; race between server readiness and schema lazy-load; a fresh Dgraph instance where the admin schema hasn't been replayed yet.

Related errors

• Not resolving %s. There's no GraphQL schema in Dgraph. Use t
• %s was not executed because no suitable resolver could be fo
• error while getting the schema for ns %d
• you must specify a 'destination' value
• Cycle detected: %s

AI-assisted analysis of dgraph-io/dgraph@759e242be6 (2026-09-01). Data as JSON: /api/errors/62a3f5d43b806fea. Report an issue: GitHub.