sqlx: bind: table: %q: unexpected number of result columns:

Error message

sqlx: bind: table: %q: unexpected number of result columns: %d: expected: %d

What it means

Bind validates that the SQL result set matches the Row definition before mapping values into the destination. When the live query returns a different number of columns than the columns declared/registered for the table, it fails with this error. It guards against silent misalignment between struct mapping and actual query output.

Source

Thrown at x/sqlx/sqlx.go:139

	typ = typ.Elem()

	originalKind := typ.Kind()
	if typ.Kind() == reflect.Slice {
		typ = typ.Elem()
	}

	r, ok := s.Rows[typ]
	if !ok {
		return fmt.Errorf("sqlx: bind: unregistered type: %q", typ.String())
	}

	columnTypes, err := src.ColumnTypes()
	if err != nil {
		return fmt.Errorf("sqlx: bind: table: %q: %w", r.Name, err)
	}

	if expected, got := len(r.Columns), len(columnTypes); expected != got {
		return fmt.Errorf("sqlx: bind: table: %q: unexpected number of result columns: %d: expected: %d", r.Name, got, expected)
	}

	val := reflex.IndirectValue(reflect.ValueOf(dst))
	if s.AutoCloseRows {
		defer src.Close()
	}

	switch originalKind {
	case reflect.Struct:
		if src.Next() {
			if err = r.bindSingle(typ, val, columnTypes, src); err != nil {
				return err
			}
		} else {
			return sql.ErrNoRows
		}

		return src.Err()

View on GitHub (pinned to 7bedaf55a0)

Solutions

Make the query's SELECT list match the registered columns exactly (select all columns of the struct, in any order but same count)
Re-register the Row so its Columns reflect the current schema/query
Avoid SELECT * if the struct intentionally maps a subset; enumerate columns explicitly
If using a DB migration, run migrations so the runtime schema matches registration

Example fix

// before
rows, err := db.Query(row, &users, "SELECT id, name FROM users")
// after
rows, err := db.Query(row, &users, "SELECT id, name, email, created_at FROM users")

Defensive patterns

Strategy: validation

Validate before calling

cols := row.Columns
if len(cols) != expectedCountFromQuery { return fmt.Errorf("query columns %d != registered %d", expectedCountFromQuery, len(cols)) }

Try / catch

if err := db.Query(row, &dst, q); err != nil { if strings.Contains(err.Error(), "unexpected number of result columns") { /* log query + registered columns */ } return err }

Prevention

Enumerate columns explicitly in SELECT instead of *
Keep Row registration in sync with migrations
Add an integration test asserting query columns match struct fields

When it happens

Trigger: Calling Query (which calls Bind) with a destination bound to a table whose registered column count differs from the SELECT list — e.g. selecting a subset of columns, adding an expression column, or the table schema changed after registration.

Common situations: Writing `SELECT id, name` but the Row was registered against a struct with more fields; a migration added/dropped a column; using `SELECT *` after a schema change; joining tables and forgetting to alias/trim columns.

Related errors

AI-assisted analysis of kataras/iris@7bedaf55a0 (2026-08-30). Data as JSON: /api/errors/e66b49f3634d7a60. Report an issue: GitHub.