unable to parse byte size, expected a size string (e.g., "5G

Error message

unable to parse byte size, expected a size string (e.g., "5GiB") or a number, but got %T

What it means

The byte-size config type accepts a size string parsed by dustin/go-humanize (e.g. "5GiB", "10MB") or a plain JSON number of bytes. Any other JSON type hits the default branch and is rejected with this error.

Source

Thrown at config/types.go:504

		*p = OptionalBytes{}
	default:
		var value any
		err := json.Unmarshal(input, &value)
		if err != nil {
			return err
		}
		switch v := value.(type) {
		case float64:
			str := fmt.Sprintf("%.0f", v)
			p.value = &str
		case string:
			_, err := humanize.ParseBytes(v)
			if err != nil {
				return err
			}
			p.value = &v
		default:
			return fmt.Errorf("unable to parse byte size, expected a size string (e.g., \"5GiB\") or a number, but got %T", v)
		}
	}
	return nil
}

var (
	_ json.Unmarshaler = (*OptionalBytes)(nil)
	_ json.Marshaler   = (*OptionalBytes)(nil)
)

type swarmLimits doNotUse

var _ json.Unmarshaler = swarmLimits(false)

func (swarmLimits) UnmarshalJSON(b []byte) error {
	d := json.NewDecoder(bytes.NewReader(b))
	for {
		switch tok, err := d.Token(); err {

View on GitHub (pinned to 329838acdf)

Solutions

Use a human-readable size string: {"StorageMax": "10GB"}.
Or use a plain byte count number: {"StorageMax": 10000000000}.
Verify the value with `ipfs config --json Datastore.StorageMax` after editing.

Example fix

// before
{"Datastore": {"StorageMax": {"size": "10GB"}}}
// after
{"Datastore": {"StorageMax": "10GB"}}

Defensive patterns

Strategy: validation

Validate before calling

func validByteSize(v any) error {
    switch t := v.(type) {
    case string:
        _, err := humanize.ParseBytes(t)
        return err
    case float64:
        return nil // raw bytes
    default:
        return fmt.Errorf("byte size must be string like \"5GiB\" or number, got %T", v)
    }
}

Type guard

func isByteSizeValue(v any) bool {
    switch t := v.(type) {
    case string:
        _, err := humanize.ParseBytes(t)
        return err == nil
    case float64:
        return true
    }
    return false
}

Try / catch

if err := json.Unmarshal(data, &cfg); err != nil {
    if strings.Contains(err.Error(), "unable to parse byte size") {
        // fix to "10GB" string or byte count number
    }
}

Prevention

Store sizes as plain strings like "10GB" or byte numbers, never nested objects
Pre-validate with humanize.ParseBytes in config generators
Round-trip test config marshal/unmarshal in CI

When it happens

Trigger: Unmarshaling a Datastore/StorageMax-style size field with an object, boolean, or array value, e.g. {"StorageMax": {"value": "10GB"}}.

Common situations: Converting config from another tool that wraps sizes in objects; hand-editing config.json with a boolean placeholder; template rendering leaving a non-scalar value.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/604dc349b416a415. Report an issue: GitHub.