vitessio/vitess · error

BuildKeyspace(%v) failed: %v

Error message

BuildKeyspace(%v) failed: %v

What it means

After successfully loading the vschema JSON, CreateKs calls vindexes.BuildKeyspace to instantiate the vindex objects referenced by the vschema. This error means the vschema parsed fine but is semantically invalid — a vindex type doesn't exist, parameters are wrong, or a table references a vindex not defined in the keyspace.

Source

Thrown at go/vt/vtcombo/tablet_map.go:411

				}
				uid++
			}
		}
	}

	// vschema for the keyspace
	if schemaDir != "" {
		f := path.Join(schemaDir, keyspace, "vschema.json")
		if _, err := os.Stat(f); err == nil {
			// load the vschema
			formal, err := vindexes.LoadFormalKeyspace(f)
			if err != nil {
				return 0, fmt.Errorf("cannot load vschema file %v for keyspace %v: %v", f, keyspace, err)
			}

			_, err = vindexes.BuildKeyspace(formal, wr.SQLParser())
			if err != nil {
				return 0, fmt.Errorf("BuildKeyspace(%v) failed: %v", keyspace, err)
			}
			ksvs := &topo.KeyspaceVSchemaInfo{
				Name:     keyspace,
				Keyspace: formal,
			}
			if err := ts.SaveVSchema(ctx, ksvs); err != nil {
				return 0, fmt.Errorf("SaveVSchema(%v) failed: %v", keyspace, err)
			}
		} else {
			log.Info(fmt.Sprintf("File %v doesn't exist, skipping vschema for keyspace %v", f, keyspace))
		}
	}

	// Rebuild the SrvKeyspace object, so we can support
	// range-based sharding queries, and export the redirects.
	if err := topotools.RebuildKeyspace(ctx, wr.Logger(), wr.TopoServer(), keyspace, nil, false); err != nil {
		return 0, fmt.Errorf("cannot rebuild %v: %v", keyspace, err)
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Read the wrapped error — it names the vindex and the semantic problem.
2. Fix vindex names in vschema.json to match registered types (hash, numeric, lookup*, etc.).
3. If using a custom vindex, ensure its package is imported/registered in the vtcombo build.
4. Verify vindex parameters against the vindex type's documented options.

Example fix

// before
{"vindexes": {"h": {"type": "hash_v2"}}, ...}
// after
{"vindexes": {"h": {"type": "hash"}}, ...}

// validate vindex references before CreateKs
formal, err := vindexes.LoadFormalKeyspace(vschemaPath)
if err == nil {
	for name, vi := range formal.Vindexes {
		if vindexes.NewVIndex(vi.Type, "", vi.Params) == nil {
			fmt.Printf("unknown vindex type %q for %s\n", vi.Type, name)
		}
	}
}

err := CreateKs(...)
if err != nil && strings.Contains(err.Error(), "BuildKeyspace") {
	return fmt.Errorf("vschema semantically invalid (check vindex types/params): %v", err)
}

When it happens

Trigger: CreateKs with a vschema.json referencing an unregistered vindex type (e.g. a custom vindex not linked in), misspelled vindex names in column_vindexes, invalid vindex parameters, or a non-consistent vindex config.

Common situations: Using a third-party/custom vindex without registering it in the build; typos like "hash" vs "unicode_loose_md5"; vschema from docs referring to vindexes removed or renamed in newer Vitess versions.

Related errors

• region_bytes must be 1 or 2: %v
• vindexType %q not found
• one or two tables must be specified
• at least one table must be specified
• vindex is in write-only mode

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