What causes "offset out of range" in vitessio/vitess?

Reduce the query minimally and check whether removing the ORDER BY/comparison on the weightstring-requiring column avoids the panic

vitessio/vitess · error

VT13001

VT13001

Error message

offset out of range

What it means

VT13001 is an internal consistency error thrown by HashJoin.AddWSColumn when the requested column offset is beyond the columns currently planned for the hash join (hj.ColumnOffsets is shorter than the offset). AddWSColumn is supposed to add a weightstring column for an existing output column; asking for a weightstring of a non-existent column means planner bookkeeping is out of sync, so it panics.

Source

Thrown at go/vt/vtgate/planbuilder/operators/hash_join.go:121

}

func (hj *HashJoin) AddColumn(ctx *plancontext.PlanningContext, reuseExisting bool, addToGroupBy bool, expr *sqlparser.AliasedExpr) int {
	if reuseExisting {
		offset := hj.FindCol(ctx, expr.Expr, false)
		if offset >= 0 {
			return offset
		}
	}

	hj.columns.add(expr.Expr)
	return len(hj.columns.columns) - 1
}

func (hj *HashJoin) AddWSColumn(ctx *plancontext.PlanningContext, offset int, underRoute bool) int {
	hj.planOffsets(ctx)

	if len(hj.ColumnOffsets) <= offset {
		panic(vterrors.VT13001("offset out of range"))
	}

	// check if it already exists
	wsExpr := weightStringFor(hj.columns.columns[offset].expr)
	if index := hj.FindCol(ctx, wsExpr, false); index != -1 {
		return index
	}

	i := hj.ColumnOffsets[offset]
	out := 0
	if i < 0 {
		out = hj.LHS.AddWSColumn(ctx, FromLeftOffset(i), underRoute)
		out = ToLeftOffset(out)
	} else {
		out = hj.RHS.AddWSColumn(ctx, FromRightOffset(i), underRoute)
		out = ToRightOffset(out)
	}
	hj.ColumnOffsets = append(hj.ColumnOffsets, out)

View on GitHub (pinned to 01a25a7d17)

Solutions

Reduce the query minimally and check whether removing the ORDER BY/comparison on the weightstring-requiring column avoids the panic
Force a different plan (e.g. add a LIMIT, reorder joins, or set flags that avoid hash join offsets) as a workaround
File a Vitess bug with the query and stack - this is an internal invariant violation, not user input validation

Defensive patterns

Strategy: try-catch

Try / catch

defer func() {
	if r := recover(); r != nil {
		if strings.Contains(fmt.Sprint(r), "VT13001") || strings.Contains(fmt.Sprint(r), "offset out of range") {
			err = vterrors.Errorf(vtrpcpb.Code_INTERNAL, "hash join offset planning bug: %v", r)
		}
	}
}()

Prevention

Report minimal reproducers - this is an internal invariant violation
Avoid relying on collation-sensitive ORDER BY across hash joins until tested
Keep Vitess updated; regressions here are fixed quickly upstream

When it happens

Trigger: Internal planner paths request AddWSColumn with an offset that was never registered via planOffsets - typically a bug in offset planning for queries combining hash joins with ORDER BY/GROUP BY on expressions requiring weightstrings (e.g. collation-sensitive ordering).

Common situations: Queries with ORDER BY or comparisons over string columns across a hash join whose collations force weightstring computation; regressions after Vitess upgrades changing offset planning; shouldn't occur for ordinary queries.

Related errors

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