{"record":{"id":"c580513365903236","repo":"vitessio/vitess","slug":"error-initilaizing-vtexplain-w","errorCode":null,"errorMessage":"error initilaizing vtexplain: %w","messagePattern":"error initilaizing vtexplain: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/vtadmin/api.go","lineNumber":2812,"sourceCode":"\t\tif err != nil {\n\t\t\ter.RecordError(err)\n\t\t\treturn\n\t\t}\n\n\t\tshardMap = fmt.Sprintf(`{\"%s\": %s}`, req.Keyspace, string(vtsb))\n\t}(c)\n\n\twg.Wait()\n\n\tif er.HasErrors() {\n\t\treturn nil, er.Error()\n\t}\n\n\tts := memorytopo.NewServer(ctx, vtexplain.Cell)\n\tsrvTopoCounts := stats.NewCountersWithSingleLabel(\"\", \"Resilient srvtopo server operations\", \"type\")\n\tvte, err := vtexplain.Init(ctx, api.env, ts, srvVSchema, schema, shardMap, &vtexplain.Options{ReplicationMode: \"ROW\"}, srvTopoCounts)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"error initilaizing vtexplain: %w\", err)\n\t}\n\tdefer vte.Stop()\n\n\tplans, err := vte.Run(req.Sql)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"error running vtexplain: %w\", err)\n\t}\n\n\tresponse, err := vte.ExplainsAsText(plans)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"error converting vtexplain to text output: %w\", err)\n\t}\n\n\treturn &vtadminpb.VTExplainResponse{\n\t\tResponse: response,\n\t}, nil\n}\n","sourceCodeStart":2794,"sourceCodeEnd":2830,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vtadmin/api.go#L2794-L2830","documentation":"After gathering the srv vschema and schemas, VTAdmin initializes an in-memory vtexplain engine (vtexplain.Init) backed by a memorytopo server. If initialization fails — bad vschema, invalid schema, inconsistent shard map, or internal errors — the request fails with this wrapped error. Note the message contains a typo ('initilaizing') that identifies this exact call site.","triggerScenarios":"vtexplain.Init returns an error, e.g. the collected srvVSchema fails validation, the schema is empty/invalid, shardMap doesn't match the vschema, or topo/tablet setup inside vtexplain fails.","commonSituations":"Keyspace has an invalid or empty vschema; schema fetch earlier returned partial/invalid definitions; sharded keyspace whose shard map conflicts with vschema vindexes; version mismatch between vtadmin and deployed vitess features used in the vschema.","solutions":["Inspect the wrapped inner error (%w chain) for the root cause — fix that first.","Validate the keyspace's vschema (e.g. `vtctldclient GetVSchema` and run it through the vschema validator / vtgate test).","Ensure the schema gathered is complete; retry if a GetSchema/GetSrvVSchema error was recorded earlier in the same request.","Re-run VTEXplain after rebuilding keyspace graph so shardMap and srv vschema are consistent.","If the vschema uses unsupported features, simplify or update to a compatible Vitess version."],"exampleFix":"// before: invalid vschema with unknown vindex type\n{\"sharded\": true, \"vindexes\": {\"h\": {\"type\": \"unknown_hash\"}}}\n// after\n{\"sharded\": true, \"vindexes\": {\"h\": {\"type\": \"hash\"}}}","handlingStrategy":"validation","validationCode":"// Validate vschema and schema before invoking vtexplain\nif len(srvVSchema.Keyspaces) == 0 {\n    return fmt.Errorf(\"empty srv vschema for keyspace %s\", ks)\n}\nif len(schemaTables) == 0 {\n    return fmt.Errorf(\"no schema tables collected for keyspace %s\", ks)\n}","typeGuard":null,"tryCatchPattern":"vte, err := vtexplain.Init(ctx, env, ts, srvVSchema, schema, shardMap, opts, counts)\nif err != nil {\n    return vterrors.Wrapf(err, vtrpcpb.Code_FAILED_PRECONDITION, \"error initializing vtexplain (check vschema/schema consistency)\")\n}","preventionTips":["Keep the keyspace vschema valid and in sync with the actual table schemas.","After topology changes, rebuild the keyspace graph so shardMap matches the srv vschema.","Test the vschema in a staging environment before applying it to the cluster vtexplain targets."],"tags":["vtadmin","vtexplain","vschema","initialization"],"backgroundTag":"vtexplain-init-failed","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}