vitessio/vitess · error

newKeyspaceIDResolverFactory failed: %v

Error message

newKeyspaceIDResolverFactory failed: %v

What it means

StreamKeyRange wraps any failure from newKeyspaceIDResolverFactory (SrvVSchema fetch, missing keyspace entry, vschema build, vindex selection) with this message. The keyrange stream could not be set up because the keyspace-id resolver could not be constructed.

Source

Thrown at go/vt/binlog/updatestreamctl.go:243

	}
	updateStream.stateWaitGroup.Add(1)
	updateStream.actionLock.Unlock()
	defer updateStream.stateWaitGroup.Done()

	streamCount.Add("KeyRange", 1)
	defer streamCount.Add("KeyRange", -1)
	log.Info(fmt.Sprintf("ServeUpdateStream starting @ %#v", pos))

	// Calls cascade like this: binlog.Streamer->keyRangeFilterFunc->func(*binlogdatapb.BinlogTransaction)->callback
	f := keyRangeFilterFunc(keyRange, func(trans *binlogdatapb.BinlogTransaction) error {
		keyrangeStatements.Add(int64(len(trans.Statements)))
		keyrangeTransactions.Add(1)
		return callback(trans)
	})
	bls := NewStreamer(updateStream.cp, updateStream.se, charset, pos, 0, f)
	bls.resolverFactory, err = newKeyspaceIDResolverFactory(ctx, updateStream.ts, updateStream.keyspace, updateStream.cell, updateStream.parser)
	if err != nil {
		return fmt.Errorf("newKeyspaceIDResolverFactory failed: %v", err)
	}

	streamCtx, cancel := context.WithCancel(ctx)
	i := updateStream.streams.Add(cancel)
	defer updateStream.streams.Delete(i)

	return bls.Stream(streamCtx)
}

// StreamTables is part of the UpdateStream interface
func (updateStream *UpdateStreamImpl) StreamTables(ctx context.Context, position string, tables []string, charset *binlogdatapb.Charset, callback func(trans *binlogdatapb.BinlogTransaction) error) (err error) {
	pos, err := replication.DecodePosition(position)
	if err != nil {
		return err
	}

	updateStream.actionLock.Lock()
	if !updateStream.IsEnabled() {

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check the wrapped inner error for the concrete factory failure (missing keyspace, vschema build, etc.).
2. Rebuild SrvVSchema (RebuildKeyspaceGraph) after any vschema change.
3. Verify keyspace/cell parameters passed to StreamKeyRange are correct.
4. Confirm the streamed tables have a valid unique sharding vindex in the vschema.

Example fix

// before (streaming before vschema applied)
streamKeyRange(ctx, kr)
// after
vtctldclient ApplyVSchema --keyspace=commerce vschema.json
vtctldclient RebuildKeyspaceGraph commerce
streamKeyRange(ctx, kr)

// validate factory preconditions before StreamKeyRange
srv, err := ts.GetSrvVSchema(ctx, cell)
if err != nil { return err }
if _, ok := srv.Keyspaces[keyspace]; !ok { return errors.New("keyspace not in SrvVSchema") }

err := updateStream.StreamKeyRange(ctx, keyrange, timestamp, callback)
if err != nil {
	if strings.Contains(err.Error(), "newKeyspaceIDResolverFactory failed") {
		log.Error("keyrange stream setup failed; check vschema/topo", slog.Any("error", err))
	}
	return err
}

When it happens

Trigger: Calling UpdateStreamImpl.StreamKeyRange where the underlying factory errors: bad cell, missing SrvVSchema entry, invalid vschema, or no sharding vindex for a table.

Common situations: Vschema not rebuilt after changes; wrong cell/keyspace flags on the stream request; keyspace unsharded or table has no sharding vindex.

Related errors

• SBR mode unsupported for streaming: %s
• value must be either a float64 (interpreted as seconds) or a
• flagutil: NewOptionalFlag requires a non-nil parse function
• flagutil: OptionalFlagValue has no parse function; use a con
• ErrStreamClosed

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