vitessio/vitess · error

unexpected number of tables returned from schema: %v

Error message

unexpected number of tables returned from schema: %v

What it means

After fetching the source table schema from the primary tablet, Vitess expects exactly one table definition back (it queried for a single table name). Any other count — typically zero — indicates the table doesn't exist on that tablet or the schema call returned unexpected results.

Source

Thrown at go/vt/wrangler/materializer.go:664

		}
	}

	// Validate against source schema
	sourceShards, err := wr.ts.GetServingShards(ctx, keyspace)
	if err != nil {
		return nil, nil, nil, err
	}
	onesource := sourceShards[0]
	if onesource.PrimaryAlias == nil {
		return nil, nil, nil, fmt.Errorf("source shard has no primary: %v", onesource.ShardName())
	}
	req := &tabletmanagerdatapb.GetSchemaRequest{Tables: []string{sourceTableName}}
	tableSchema, err := schematools.GetSchema(ctx, wr.ts, wr.tmc, onesource.PrimaryAlias, req)
	if err != nil {
		return nil, nil, nil, err
	}
	if len(tableSchema.TableDefinitions) != 1 {
		return nil, nil, nil, fmt.Errorf("unexpected number of tables returned from schema: %v", tableSchema.TableDefinitions)
	}

	// Generate "create table" statement
	lines := strings.Split(tableSchema.TableDefinitions[0].Schema, "\n")
	if len(lines) < 3 {
		// Unreachable
		return nil, nil, nil, fmt.Errorf("schema looks incorrect: %s, expecting at least four lines", tableSchema.TableDefinitions[0].Schema)
	}
	var modified []string
	modified = append(modified, strings.Replace(lines[0], sourceTableName, targetTableName, 1))
	for i := range sourceVindexColumns {
		line, err := generateColDef(lines, sourceVindexColumns[i], vindexFromCols[i])
		if err != nil {
			return nil, nil, nil, err
		}
		modified = append(modified, line)
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Verify the table exists on the source primary (`SHOW TABLES`) and create it if missing
2. Double-check the keyspace/table name passed to CreateLookupVindex
3. Reload the tablet schema (`vtctldclient ReloadSchema`) and retry

Example fix

null

tds, err := schematools.GetSchema(ctx, ts, tmc, primaryAlias, &tabletmanagerdatapb.GetSchemaRequest{Tables: []string{sourceTableName}})
if err != nil { return err }
if len(tds.TableDefinitions) != 1 {
    return fmt.Errorf("table %s must exist exactly once on the source primary", sourceTableName)
}

func exactlyOneTableDef(s *tabletmanagerdatapb.SchemaResult) *tabletmanagerdatapb.TableDefinition {
    if len(s.TableDefinitions) == 1 { return s.TableDefinitions[0] }
    return nil
}

if err := createLookupVindex(...); err != nil {
    if strings.Contains(err.Error(), "unexpected number of tables returned") {
        return ensureTableExists(ks, table) // create/reload schema, then retry
    }
    return err
}

When it happens

Trigger: GetSchema on the source shard's primary returned zero or multiple TableDefinitions for the requested source table — usually because the table does not exist on that tablet (fresh replica set, wrong keyspace) or the filtered result unexpectedly matched more than once.

Common situations: Table name typo; table exists in the vschema but was never created in MySQL on the source shard; running against a shard whose schema wasn't restored; schema reload lag after a manual DROP/CREATE.

Related errors

• cannot compile regexp %v for table: %v
• cannot compile regexp %v for excludeTable: %v
• schemas are different: %s: %v, %s: %v
• schemas are different: %s: %v differs from: %s: %v
• %v has an extra table named %v

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