unknwon/the-way-to-go_ZH_CN · error

%d is out of the uint8 range

Error message

%d is out of the uint8 range

What it means

Range-guard error from the safe-conversion helper in section 4.5: Uint8FromInt(n int) allows only 0..math.MaxUint8 and otherwise returns 0 plus fmt.Errorf("%d is out of the uint8 range", n). The book introduces it because Go's raw int→uint8 conversion silently truncates (keeps the low 8 bits), so a checked helper is the way to make narrowing conversions safe and reportable.

Source

Thrown at eBook/04.5.md:201

16 bit int is: 34
```

**格式化说明符**

在格式化字符串里，`%d` 用于格式化整数（`%x` 和 `%X` 用于格式化 16 进制表示的数字），`%g` 用于格式化浮点型（`%f` 输出浮点数，`%e` 输出科学计数表示法），`%0nd` 用于规定输出长度为 n 的整数，其中开头的数字 0 是必须的。

`%n.mg` 用于表示数字 n 并精确到小数点后 m 位，除了使用 g 之外，还可以使用 e 或者 f，例如：使用格式化字符串 `%5.2e` 来输出 3.4 的结果为 `3.40e+00`。

**数字值转换**

当进行类似 `a32bitInt = int32(a32Float)` 的转换时，小数点后的数字将被丢弃。这种情况一般发生当从取值范围较大的类型转换为取值范围较小的类型时，或者你可以写一个专门用于处理类型转换的函数来确保没有发生精度的丢失。下面这个例子展示如何安全地从 `int` 型转换为 `int8`：

```go
func Uint8FromInt(n int) (uint8, error) {
	if 0 <= n && n <= math.MaxUint8 { // conversion is safe
		return uint8(n), nil
	}
	return 0, fmt.Errorf("%d is out of the uint8 range", n)
}
```

或者安全地从 `float64` 转换为 `int`：

```go
func IntFromFloat64(x float64) int {
	if math.MinInt32 <= x && x <= math.MaxInt32 { // x lies in the integer range
		whole, fraction := math.Modf(x)
		if fraction >= 0.5 {
			whole++
		}
		return int(whole)
	}
	panic(fmt.Sprintf("%g is out of the int32 range", x))
}
```

View on GitHub (pinned to 7a54d34d36)

Solutions

1. Clamp before converting when saturation is the correct behavior: n = min(max(n, 0), math.MaxUint8)
2. Reject at the input boundary: validate parsed config values against [0,255] with a clear message before any conversion happens
3. Widen the destination field (int32/int64) so the range question disappears
4. Apply the same checked-helper pattern (the sibling IntFromFloat64 in this section) to every narrowing conversion in the path so overflow is caught once, precisely

Example fix

// before
b := uint8(n) // n = 300 → 44; silent wraparound, no error

// after
b, err := Uint8FromInt(n)
if err != nil {
	return fmt.Errorf("channel value: %v", err)
}

func fitsUint8(n int) bool {
	return n >= 0 && n <= math.MaxUint8
}

if !fitsUint8(n) {
	return fmt.Errorf("rejecting %d before conversion", n)
}
b := uint8(n)

b, err := Uint8FromInt(n)
if err != nil {
	return fmt.Errorf("field out of range: %v", err)
}

When it happens

Trigger: Calling Uint8FromInt with n < 0 or n > 255. Raw uint8(n) would wrap 256→0 and -1→255; the helper catches exactly those cases. Typical sources: sums exceeding 255 (color channels, byte counters, scaled percentages) or signed intermediates that dipped negative.

Common situations: Image/audio processing where per-sample math overflows a byte; config values parsed as int from flags or JSON then narrowed; cross-platform code where int is 64-bit and masks produce large values; porting C code that relied on implicit wraparound.

Related errors

• %d is out of the int32 range
• stack is empty
• I won't be able to do a sqrt of negative number!
• math - square root of negative number
• Not found error

AI-assisted analysis of unknwon/the-way-to-go_ZH_CN@7a54d34d36 (2026-08-15). Data as JSON: /api/errors/f5273c1a653bb2fa. Report an issue: GitHub.