{"record":{"id":"cdab2155d94e692a","repo":"vitessio/vitess","slug":"vt09003","errorCode":"VT09003","errorMessage":"VT09003: INSERT query does not have primary vindex column '%v' in the column list","messagePattern":"VT09003: INSERT query does not have primary vindex column '(.+?)' in the column list","errorType":"error_code","errorClass":"VitessError","httpStatus":null,"severity":"error","filePath":"go/vt/vtgate/planbuilder/operators/insert.go","lineNumber":451,"sourceCode":"\tinsertTbl := insOp.tableTarget()\n\tselTables := TablesUsed(selOp)\n\tif slices.Contains(selTables, insertTbl) {\n\t\tinsertSelect.ForceNonStreaming = true\n\t}\n\n\tif len(insOp.ColVindexes) == 0 {\n\t\treturn insertSelect\n\t}\n\n\tcolVindexes := insOp.ColVindexes\n\tvv := make([][]int, len(colVindexes))\n\tfor idx, colVindex := range colVindexes {\n\t\tfor _, col := range colVindex.Columns {\n\t\t\tcheckAndErrIfVindexChanging(sqlparser.UpdateExprs(ins.OnDup), col)\n\t\t\tcolNum := findColumn(ins, col)\n\t\t\t// sharding column values should be provided in the insert.\n\t\t\tif colNum == -1 && idx == 0 {\n\t\t\t\tpanic(vterrors.VT09003(col))\n\t\t\t}\n\t\t\tvv[idx] = append(vv[idx], colNum)\n\t\t}\n\t}\n\tinsOp.VindexValueOffset = vv\n\treturn insertSelect\n}\n\nfunc columnMismatch(gen *Generate, ins *sqlparser.Insert, sel sqlparser.TableStatement) bool {\n\torigColCount := len(ins.Columns)\n\tif gen != nil && gen.added {\n\t\t// One column got added to the insert query ast for auto increment column.\n\t\t// adjusting it here for comparison.\n\t\torigColCount--\n\t}\n\tif origColCount < sel.GetColumnCount() {\n\t\treturn true\n\t}","sourceCodeStart":433,"sourceCodeEnd":469,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vtgate/planbuilder/operators/insert.go#L433-L469","documentation":"VT09003 is raised by insertSelectPlan in go/vt/vtgate/planbuilder/operators/insert.go:451 when an `INSERT ... SELECT` does not include the primary vindex column in its column list. Vitess must know the primary vindex value to route each row, so the first column vindex's columns must be present in the insert columns.","triggerScenarios":"INSERT INTO t (a, b) SELECT ... where t's primary vindex column is `id` and `id` is missing from the column list (findColumn returns -1 for idx == 0).","commonSituations":"Assuming Vitess will auto-generate the sharding/primary key in INSERT..SELECT; copying column lists from single-shard MySQL code to sharded Vitess tables; vschema primary vindex changed to a different column.","solutions":["Add the primary vindex column to the INSERT column list and supply its value in the SELECT","If the column is auto-increment, omit it from the column list entirely so modifyForAutoinc handles generation","Confirm which column(s) form the first (primary) column vindex in the vschema"],"exampleFix":"// before\nINSERT INTO t (name) SELECT name FROM other;\n// after\nINSERT INTO t (id, name) SELECT other_id, name FROM other;","handlingStrategy":"validation","validationCode":"// Check the primary vindex column is present in the INSERT column list\nconst primaryVindexCols = vschema.tables['t'].column_vindexes[0].columns;\nconst missing = primaryVindexCols.filter(c => !insertCols.includes(c));\nif (missing.length) throw new Error('primary vindex columns missing from INSERT: ' + missing.join(','));","typeGuard":"function hasPrimaryVindexColumns(insertCols, vindexes) {\n  const primary = vindexes[0].columns || [vindexes[0].column];\n  return primary.every(c => insertCols.map(x => x.toLowerCase()).includes(c.toLowerCase()));\n}","tryCatchPattern":"try {\n  await vtgate.execute(sql, args);\n} catch (e) {\n  if (String(e).includes('VT09003')) {\n    throw new Error('Add the primary vindex column to the INSERT column list and supply it in the SELECT');\n  }\n  throw e;\n}","preventionTips":["Document the primary vindex columns of every sharded table","Include primary-vindex columns explicitly in all INSERT..SELECT statements","Omit auto-increment primary keys instead of supplying them ad hoc"],"tags":["insert-select","vindex","sharding"],"backgroundTag":"missing-primary-vindex-column","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}