infiniflow/ragflow · error · listOpPanic

ListOperations: head requires n to be within the valid range

Error message

ListOperations: head requires n to be within the valid range in strict mode, got %d

What it means

opHead panics in strict mode when n < 1 or n > len(items). Strict mode enforces the full contract 1 <= n <= len(items) for the head operation (first n items); zero, negative, or oversized n is treated as a caller error and panics via strictRangePanic instead of being clamped or returning an empty list.

Source

Thrown at internal/agent/component/list_operations.go:414

		}
		return []any{}
	}
	absN := -n
	if absN <= len(items) {
		return []any{items[n]}
	}
	if l.param.Strict {
		panic(strictRangePanic("nth", n))
	}
	return []any{}
}

// opHead: first n items. n < 1 → empty. Strict: 1 ≤ n ≤ len(items).
func (l *ListOperationsComponent) opHead(items []any) []any {
	n := l.param.N
	if l.param.Strict {
		if n < 1 || n > len(items) {
			panic(strictRangePanic("head", n))
		}
		return append([]any{}, items[:n]...)
	}
	if n < 1 {
		return []any{}
	}
	if n > len(items) {
		n = len(items)
	}
	return append([]any{}, items[:n]...)
}

// opTail: last n items. n < 1 → empty. Strict: 1 ≤ n ≤ len(items).
func (l *ListOperationsComponent) opTail(items []any) []any {
	n := l.param.N
	if l.param.Strict {
		if n < 1 || n > len(items) {
			panic(strictRangePanic("tail", n))

View on GitHub (pinned to 554fb1133a)

Solutions

1. Set N to a value between 1 and the input list length
2. If the upstream list can be empty, branch before head runs (strict head on an empty list always violates 1 <= n)
3. Turn strict mode off to get the lenient behavior: n < 1 returns empty, n > len clamps to the whole list

Example fix

# before
operation: head
strict: true
n: 0        # panic: head requires n to be within the valid range

# after
operation: head
strict: true
n: 1        # first item

if op == "head" && strict && (n < 1 || n > len(items)) {
    return fmt.Errorf("head requires 1 <= n <= %d, got %d", len(items), n)
}

When it happens

Trigger: ListOperations with operation head, Strict: true, and N set to 0, negative, or greater than the number of input items.

Common situations: N defaults to 0 because the parameter was never set; a computed count evaluates to 0 on empty/filtered upstream lists; hardcoded head size from a larger dataset reused on a smaller one.

Related errors

• ListOperations: tail requires n to be within the valid range
• ListOperations: nth requires n to be within the valid range
• should be a numeric number between 0 and 1 exclusively
• {operation} requires n to be within the valid range in stric
• failed to initialize logger: {err}

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/717e626ff118211d. Report an issue: GitHub.