wavetermdev/waveterm · error

offset must be non-negative, got %d

Error message

offset must be non-negative, got %d

What it means

The "offset" parameter is a line offset and must be zero or positive. Negative offsets have no defined meaning (no backward seeking past start), so parseReadTextFileInput rejects them before reading.

Source

Thrown at pkg/aiusechat/tools_readfile.go:62

		return nil, fmt.Errorf("missing filename parameter")
	}

	if result.Origin == nil {
		origin := "start"
		result.Origin = &origin
	}

	if *result.Origin != "start" && *result.Origin != "end" {
		return nil, fmt.Errorf("invalid origin value '%s': must be 'start' or 'end'", *result.Origin)
	}

	if result.Offset == nil {
		offset := 0
		result.Offset = &offset
	}

	if *result.Offset < 0 {
		return nil, fmt.Errorf("offset must be non-negative, got %d", *result.Offset)
	}

	if result.Count == nil {
		count := ReadFileDefaultLineCount
		result.Count = &count
	}

	if *result.Count < 1 {
		return nil, fmt.Errorf("count must be at least 1, got %d", *result.Count)
	}

	if result.MaxBytes == nil {
		maxBytes := ReadFileDefaultMaxBytes
		result.MaxBytes = &maxBytes
	}

	return result, nil
}

View on GitHub (pinned to a4447c1563)

Solutions

1. Clamp offset to >= 0 before the call (Math.max(0, offset)).
2. Omit "offset" to read from the start (defaults to 0).
3. Use origin "end" with a non-negative offset to read from the tail instead of negative math.

Example fix

// before
{"filename": "/tmp/a.txt", "offset": -5}
// after
const offset = Math.max(0, want - 5);
read_text_file({"filename": "/tmp/a.txt", "offset": offset})

const safeOffset = Number.isInteger(offset) && offset >= 0 ? offset : 0;

func validOffset(o int) bool { return o >= 0 }

params, err := parseReadTextFileInput(input)
if err != nil && strings.HasPrefix(err.Error(), "offset must be non-negative") {
    // clamp to 0 and retry
}

When it happens

Trigger: Passing {"offset": -1} or any negative integer, e.g. when an agent computes offset = matchLine - N without clamping at 0.

Common situations: Paging backwards from a match near the top of a file; arithmetic on line numbers producing negatives; copying offset semantics from byte-based APIs that allow negatives.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• count must be at least 1, got %d
• input is required
• missing filename parameter
• invalid origin value '%s': must be 'start' or 'end'
• integer overflow

AI-assisted analysis of wavetermdev/waveterm@a4447c1563 (2026-09-01). Data as JSON: /api/errors/072be689f2cf4bc7. Report an issue: GitHub.