{"record":{"id":"961d962555bc868d","repo":"vitessio/vitess","slug":"vt03014","errorCode":"VT03014","errorMessage":"VT03014: unknown column '%s' in '%s'","messagePattern":"VT03014: unknown column '(.+?)' in '(.+?)'","errorType":"error_code","errorClass":"VitessError","httpStatus":null,"severity":"error","filePath":"go/vt/vtgate/planbuilder/operators/insert.go","lineNumber":254,"sourceCode":"\t\t\tdef = findDefault(vTbl, pCol)\n\t\t\tif def == nil {\n\t\t\t\t// If default value is empty, nothing to compare as it will always be false.\n\t\t\t\treturn nil, nil\n\t\t\t}\n\t\t}\n\t\tpIndexes = append(pIndexes, pComp{idx, def, pCol})\n\t\tpColTuple = append(pColTuple, sqlparser.NewColName(pCol.String()))\n\t}\n\treturn\n}\n\nfunc findDefault(vTbl *vindexes.BaseTable, pCol sqlparser.IdentifierCI) sqlparser.Expr {\n\tfor _, column := range vTbl.Columns {\n\t\tif column.Name.Equal(pCol) {\n\t\t\treturn column.Default\n\t\t}\n\t}\n\tpanic(vterrors.VT03014(pCol.String(), vTbl.Name.String()))\n}\n\ntype uComp struct {\n\tidx int\n\tdef sqlparser.Expr\n}\n\nfunc uniqKeyCompExpressions(vTbl *vindexes.BaseTable, ins *sqlparser.Insert, rows sqlparser.Values) (comps []*sqlparser.ComparisonExpr) {\n\tnoOfUniqKeys := len(vTbl.UniqueKeys)\n\tif noOfUniqKeys == 0 {\n\t\treturn nil\n\t}\n\n\ttype uIdx struct {\n\t\tIndexes [][]uComp\n\t\tuniqKey []sqlparser.Expr\n\t}\n","sourceCodeStart":236,"sourceCodeEnd":272,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vtgate/planbuilder/operators/insert.go#L236-L272","documentation":"VT03014 is raised by findDefault in go/vt/vtgate/planbuilder/operators/insert.go:254 when an INSERT references a column that exists in the query's column list but cannot be found in the vschema's authoritative column definitions for the target table. Vitess panics with this error (recovered as a query error) because it needs the column's DEFAULT expression to build the insert plan and cannot proceed without it. It indicates a mismatch between the columns the client is inserting and the columns known to the vschema.","triggerScenarios":"Calling findDefault (via findPKIndexes or createUniqueKeyComp during INSERT planning) with a pCol that does not match any column.Name in vTbl.Columns — i.e. the insert column list contains a column absent from the vschema table definition.","commonSituations":"Vschema is out of date after an ALTER TABLE added a column; a typo in the INSERT column list; inserting into a view or table whose vschema entry omits columns; ColumnListAuthoritative set incorrectly so Vitess trusts an incomplete column list.","solutions":["Update the vschema (rebuild the table definition) so it includes the column being inserted","Check the INSERT column list for typos against SHOW COLUMNS on the underlying table","Verify ColumnListAuthoritative is only set on tables whose vschema column list truly matches the physical table"],"exampleFix":"// before (vschema missing new column)\n\"t\": {\"column_vindexes\": [...], \"columns\": [{\"name\": \"id\"}, {\"name\": \"name\"}]}\n// after\n\"t\": {\"column_vindexes\": [...], \"columns\": [{\"name\": \"id\"}, {\"name\": \"name\"}, {\"name\": \"email\"}]}","handlingStrategy":"validation","validationCode":"// Compare INSERT columns against the vschema table definition before executing\nconst cols = new Set(Object.keys(vschema.tables['t'].columns || {}));\nconst missing = insertColumns.filter(c => !cols.has(c));\nif (missing.length) throw new Error('columns not in vschema: ' + missing.join(','));","typeGuard":"function isKnownColumn(col, vTbl) {\n  return vTbl.columns.some(c => c.name.toLowerCase() === col.toLowerCase());\n}","tryCatchPattern":"try {\n  await vtgate.execute('INSERT INTO t (col) VALUES (?)', [v]);\n} catch (e) {\n  if (String(e).includes('VT03014')) {\n    await refreshVschema(); // reload table definitions, then retry\n  }\n  throw e;\n}","preventionTips":["Regenerate/reload the vschema after every ALTER TABLE","Keep column lists in the vschema authoritative only when they are complete","Lint INSERT statements against SHOW COLUMNS output in CI"],"tags":["vschema","insert","query-planning"],"backgroundTag":"unknown-column-in-vschema","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}