vitessio/vitess · error

ReloadSchemaKeyspace(%s) failed: %w

Error message

ReloadSchemaKeyspace(%s) failed: %w

What it means

During Cluster.ReloadSchemas, each keyspace's schema reload runs in a goroutine and its error is collected via errgroup's rec.RecordError, wrapped as 'ReloadSchemaKeyspace(%s) failed'. The wrapper only adds the keyspace name; the cause is the underlying vtctld ReloadSchema call failure.

Source

Thrown at go/vt/vtadmin/cluster/cluster.go:2256

			defer wg.Done()

			span, ctx := trace.NewSpan(ctx, "Cluster.ReloadSchemaKeyspace")
			defer span.Finish()

			AnnotateSpan(c, span)
			span.Annotate("keyspace", ks.Name)
			span.Annotate("concurrency", req.Concurrency)
			span.Annotate("include_primary", req.IncludePrimary)
			span.Annotate("wait_position", req.WaitPosition)

			resp, err := c.Vtctld.ReloadSchemaKeyspace(ctx, &vtctldatapb.ReloadSchemaKeyspaceRequest{
				Keyspace:       ks.Name,
				Concurrency:    req.Concurrency,
				IncludePrimary: req.IncludePrimary,
				WaitPosition:   req.WaitPosition,
			})
			if err != nil {
				rec.RecordError(fmt.Errorf("ReloadSchemaKeyspace(%s) failed: %w", ks.Name, err))
				return
			}

			m.Lock()
			defer m.Unlock()
			results = append(results, &vtadminpb.ReloadSchemasResponse_KeyspaceResult{
				Keyspace: &vtadminpb.Keyspace{
					Cluster:  cpb,
					Keyspace: ks,
				},
				Events: resp.Events,
			})
		}(ks)
	}

	wg.Wait()
	if rec.HasErrors() {
		return nil, rec.Error()

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Inspect the wrapped cause in the collected error for the failing tablet
2. Re-run ReloadSchemas for just the affected keyspace after tablets recover
3. Remove/decommission unhealthy tablets or fix connectivity to the cell
4. Check WaitPosition validity if one was supplied in the request

Example fix

// before
rec.RecordError(fmt.Errorf("ReloadSchemaKeyspace(%s) failed: %w", ks.Name, err))
// after (operator: inspect the cause)
log.Error("schema reload failed", slog.String("keyspace", ks.Name), slog.Any("error", err))
// then retry:
_, err := c.ReloadSchemaKeyspace(ctx, &vtctldatapb.ReloadSchemaKeyspaceRequest{Keyspace: ks.Name})

res, err := c.ReloadSchemas(ctx, req)
if err != nil {
    var ksErr string
    if strings.Contains(err.Error(), "ReloadSchemaKeyspace(") {
        // extract keyspace and underlying cause; retry per-keyspace
    }
}

When it happens

Trigger: vtctld ReloadSchema for a specific keyspace fails — tablet unreachable, tablet RPC timeout, some tablets error during reload, or context deadline exceeded mid-reload.

Common situations: A tablet down or draining during a cluster-wide schema reload (e.g. after a DDL/migration); network partition to one cell; WaitPosition set to an unknown binlog position after a failed migration.

Related errors

• ReloadSchemaShard(%s/%s) failed: %w
• ReloadSchemas: failed to acquire topoReadPool: %w
• not allowed: deny-all security-policy enforced
• not allowed: read-only security-policy enforced
• invalid joined path

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/6ba4e06fe521af5a. Report an issue: GitHub.