vitessio/vitess · error

unable to resolve table name %s

Error message

unable to resolve table name %s

What it means

When resolving the FROM tables of a select, vtexplain looks up each table name in the preloaded tableColumns map of the global tablet environment. If a table name is non-empty and not found there, it cannot determine column types for the simulated result and returns this error. This mirrors error 1220 but for the select-planning path.

Source

Thrown at go/vt/vtexplain/vtexplain_vttablet.go:647

	}

	// Gen4 supports more complex queries so we now need to
	// handle multiple FROM clauses
	tables := make([]*sqlparser.AliasedTableExpr, 0, len(selStmt.From))
	for _, from := range selStmt.From {
		tables = append(tables, getTables(from)...)
	}

	tableColumnMap := map[sqlparser.IdentifierCS]map[string]querypb.Type{}
	for _, table := range tables {
		if table == nil {
			continue
		}

		tableName := sqlparser.String(sqlparser.GetTableName(table.Expr))
		columns, exists := t.vte.getGlobalTabletEnv().tableColumns[tableName]
		if !exists && tableName != "" {
			return nil, fmt.Errorf("unable to resolve table name %s", tableName)
		}

		colTypeMap := map[string]querypb.Type{}

		if table.As.IsEmpty() {
			tableColumnMap[sqlparser.GetTableName(table.Expr)] = colTypeMap
		} else {
			tableColumnMap[table.As] = colTypeMap
		}

		for k, v := range columns {
			if colType, exists := colTypeMap[k]; exists {
				if colType != v {
					return nil, fmt.Errorf("column type mismatch for column : %s, types: %d vs %d", k, colType, v)
				}
				continue
			}
			colTypeMap[k] = v

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Add the missing table's CREATE TABLE to the vtexplain schema.
2. Correct the table name/keyspace qualifier in the SELECT.
3. Verify the schema file loaded actually contains all tables used in the workload.

Example fix

// before
select * from missing_table; // not in schema
// after
create table missing_table (id int); // add to --schema
select * from missing_table;

for _, t := range fromTables(sel) {
    name := sqlparser.String(sqlparser.GetTableName(t.Expr))
    if _, ok := env.tableColumns[name]; !ok && name != "" {
        return fmt.Errorf("table %s not in schema", name)
    }
}

if err != nil && strings.Contains(err.Error(), "unable to resolve table name") {
    // regenerate schema file including the missing table, then retry
}

When it happens

Trigger: Explaining a SELECT whose FROM table is not present in the schema loaded into vtexplain (tableColumns map missing the key).

Common situations: SELECT referencing a table absent from the --schema input; wrong keyspace-qualified name; subquery or join referencing an undefined table; schema file outdated after a table rename.

Related errors

• GetSchema(%s): %w
• column type mismatch for column : %s, types: %d vs %d
• not allowed: deny-all security-policy enforced
• BeforeSchema differs
• AfterSchema differs

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