What causes "index out of range" in milvus-io/milvus?

Switch from MustValue(idx) to Value(idx), which performs the same valueIndex translation plus rangeCheck and returns an error instead of panicking

milvus-io/milvus · error

index out of range

Error message

index out of range

What it means

This panic comes from the Milvus Go client's column accessor MustValue (client/column/generic_base.go:313). MustValue is the unchecked variant of Value(idx): instead of returning an error it panics when the resolved index is not usable. The index is first translated by valueIndex — for a nullable, non-sparse (dense) column this maps the row position through c.indexMapping, which stores -1 for rows that are null — and the explicit guard `idx < 0 || idx > c.Len()` then trips on both out-of-bounds row numbers and on null rows. Note the library intends this: use Value(idx) for the error-returning path.

Source

Thrown at client/column/generic_base.go:313

	}
	return c.values[idx], nil
}

func (c *genericColumnBase[T]) valueIndex(idx int) int {
	if !c.nullable || c.sparseMode {
		return idx
	}
	return c.indexMapping[idx]
}

func (c *genericColumnBase[T]) Data() []T {
	return c.values
}

func (c *genericColumnBase[T]) MustValue(idx int) T {
	idx = c.valueIndex(idx)
	if idx < 0 || idx > c.Len() {
		panic("index out of range")
	}
	return c.values[idx]
}

func (c *genericColumnBase[T]) AppendNull() error {
	if !c.nullable {
		return errors.New("append null to not nullable column")
	}

	c.validData = append(c.validData, false)
	if c.sparseMode {
		var zero T
		c.values = append(c.values, zero)
	} else {
		c.indexMapping = append(c.indexMapping, -1)
	}
	return nil
}

View on GitHub (pinned to b43a76673a)

Solutions

Switch from MustValue(idx) to Value(idx), which performs the same valueIndex translation plus rangeCheck and returns an error instead of panicking
If the row may be null, check the null status first (e.g. column valid data / GetAsNull or the entity's IsNull-style check) and skip or default null rows before calling MustValue
Fix off-by-one loops: iterate with `i < col.Len()`, never `i <=`
Verify idx was computed against the same column object (or its Slice result) you are indexing

Example fix

// before
for i := 0; i <= rows; i++ { // off-by-one, or row i may be NULL
    v := col.MustValue(i)
}

// after
for i := 0; i < col.Len(); i++ {
    v, err := col.Value(i)
    if err != nil {
        return err // covers out-of-range AND null-mapped (-1) indices
    }
    _ = v
}

Defensive patterns

Strategy: validation

Validate before calling

// Guard before MustValue: bounds + null-slot check.
// For nullable dense columns a null row maps to -1 internally,
// so bounds alone are not enough — prefer Value() which returns an error.
func safeValue[T any](c interface {
    Value(idx int) (T, error)
    Len() int
}, idx int) (T, error) {
    if idx < 0 || idx >= c.Len() {
        var z T
        return z, fmt.Errorf("index %d out of range (len %d)", idx, c.Len())
    }
    return c.Value(idx) // error-returning path, no panic
}

Try / catch

// Go has no try/catch; if you must call MustValue on untrusted indices,
// wrap with recover and convert to an error.
func mustValueSafe[T any](c *column.genericColumnBase[T], idx int) (v T, err error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("column access failed: %v", r)
        }
    }()
    return c.MustValue(idx), nil
}

Prevention

Prefer the Value/GetAsX family (error-returning) over MustValue wherever input indices or nullability are not fully controlled
Never iterate with `i <= col.Len()`
For nullable columns, handle null rows explicitly (skip or default) before any Must* accessor
Compute indices from the same column you index, especially after Slice()

When it happens

Trigger: 1) Calling column.MustValue(i) with i >= column.Len() or i < 0. 2) Calling MustValue(i) on a row that was appended with AppendNull() on a nullable dense column: valueIndex returns indexMapping[i] == -1, which fails the `idx < 0` check even though i is a valid row number. 3) Reusing an index obtained from another column of different length (e.g. iterating with the result-set row count against a sliced column).

Common situations: Looping `for i := 0; i <= col.Len(); i++` (off-by-one <= instead of <); reading fields of a row where some fields are NULL while using MustValue instead of Value; mixing indices between a nullable column and a non-nullable column in the same row; upgrading code from MustValue on data known to contain nulls after enabling nullable schema fields.

Related errors

AI-assisted analysis of milvus-io/milvus@b43a76673a (2026-08-15). Data as JSON: /api/errors/9d96021819efaf84. Report an issue: GitHub.