cannot scan redis.result %s into struct field %s.%s of type

Error message

cannot scan redis.result %s into struct field %s.%s of type %s, error-%s

What it means

When a per-field decoder fails while scanning a Redis hash result into a struct field (e.g. 'strconv.ParseInt: parsing "abc"' for an int field), hscan wraps the failure with full context: the raw value, the struct name, the field name, the field type, and the underlying error. It points at a type mismatch between the stored Redis string and the declared Go field type.

Source

Thrown at internal/hscan/structmap.go:123

	if isPtr && v.Type().NumMethod() > 0 && v.CanInterface() {
		switch scan := v.Interface().(type) {
		case Scanner:
			return scan.ScanRedis(value)
		case encoding.TextUnmarshaler:
			return scan.UnmarshalText(util.StringToBytes(value))
		case encoding.BinaryUnmarshaler:
			return scan.UnmarshalBinary(util.StringToBytes(value))
		}
	}

	if isPtr {
		v = v.Elem()
	}

	if err := field.fn(v, value); err != nil {
		t := s.value.Type()
		return fmt.Errorf("cannot scan redis.result %s into struct field %s.%s of type %s, error-%s",
			value, t.Name(), t.Field(field.index).Name, t.Field(field.index).Type, err.Error())
	}
	return nil
}

View on GitHub (pinned to c5cad058c7)

Solutions

Read the embedded error-%s suffix to see the exact parse failure
Fix the struct field type to match the stored data (e.g. int64 for large numbers)
Clean/normalize the stored data or handle sentinel values before scanning
Use a string field and parse manually when values may be non-numeric

Example fix

// before
type User struct {
	Age uint `redis:"age"` // stored: "-5"
}
// after
type User struct {
	Age int64 `redis:"age"`
}

Defensive patterns

Strategy: try-catch

Try / catch

if err := redis.Scan(&user); err != nil {
	var scanErr string = err.Error()
	if strings.HasPrefix(scanErr, "cannot scan redis.result") {
		// parse field name and underlying cause from the message
		log.Printf("schema/data mismatch: %s", scanErr)
	}
	return err
}

Prevention

Match Go field types to the actual stored Redis values
Widen numeric fields (int64) to avoid range errors
Guard nullable/empty stored values with string fields and manual parsing
Add integration tests scanning real production-shaped data

When it happens

Trigger: HGETALL returns a non-numeric or out-of-range string for an int/float/bool field; a negative value scanned into a uint field; empty string decoded into a number.

Common situations: Data written by another app in a different format; schema drift where a field changed type; Redis values like 'nil' or '' stored where numbers are expected.

Related errors

AI-assisted analysis of redis/go-redis@c5cad058c7 (2026-09-01). Data as JSON: /api/errors/0bf8dea4a152e645. Report an issue: GitHub.