grafana/k6 · error

value overflows int32

Error message

value %d overflows int32

What it means

The primitive overflow error from toInt32 (internal/cloudapi/provisioning/api.go:298): a value passed into StartLocalExecution (max_vus, total_duration, or archive_size) is outside the int32 range [-2147483648, 2147483647] that the k6 Cloud OpenAPI SDK requires. Callers normally see it wrapped with a field-name prefix ('max_vus: value 2147483648 overflows int32'), which tells you which field overflowed. It is a hard pre-flight rejection — no HTTP request is made.

Solutions

  1. Read the field name in the wrapped message to identify which value overflowed, then inspect how the caller computed it.
  2. For archive_size: shrink the archive or use --no-archive-upload (0 → JSON null is valid).
  3. For durations/VUs: verify units (seconds, count) and replace sentinel negatives with real computed values.
  4. Add range validation at the request-construction site so the failure surfaces with context before StartLocalExecution.
Defensive patterns

Strategy: validation

Validate before calling

// Central guard for all int32-bound request fields.
func fitsInt32(v int64) bool {
	return v >= math.MinInt32 && v <= math.MaxInt32
}

for name, v := range map[string]int64{
	"max_vus": req.MaxVUs, "total_duration": req.TotalDuration, "archive_size": req.ArchiveSize,
} {
	if !fitsInt32(v) {
		return fmt.Errorf("%s=%d exceeds int32 range; check how this value is computed", name, v)
	}
}

Try / catch

if _, err := c.StartLocalExecution(ctx, id, req); err != nil {
	if strings.Contains(err.Error(), "overflows int32") {
		// permanent input error — locate the offending field from the prefix and fix upstream
		return err
	}
}

Prevention

When it happens

Trigger: req.MaxVUs, req.TotalDuration, or req.ArchiveSize (only when > 0) exceeding math.MaxInt32 or dropping below math.MinInt32 at the toInt32 call sites in StartLocalExecution (api.go:204, 208, 216).

Common situations: The realistic case is ArchiveSize > ~2 GiB; the other two almost always indicate unit confusion or -1 sentinels from the calling code; SDK clients in other languages mapping these fields to 64-bit ints and forwarding unchecked values.

Related errors

AI-assisted analysis of grafana/k6@01ffac6f24 (2026-08-18). Data as JSON: /api/errors/e6abddb3b541d245. Report an issue: GitHub.

Appendix: source

Thrown at internal/cloudapi/provisioning/api.go:298

				PushPeriodSeconds: l.GetPushPeriodSeconds(),
				MessageMaxSize:    l.GetMessageMaxSize(),
				AllowedLabels:     l.GetAllowedLabels(),
			},
		},
	}

	if url := res.ArchiveUploadUrl.Get(); url != nil {
		resp.ArchiveUploadURL = url
	}

	return resp
}

// toInt32 safely converts an int64 to int32, returning an error if
// the value overflows.
func toInt32(v int64) (int32, error) {
	if v < math.MinInt32 || v > math.MaxInt32 {
		return 0, fmt.Errorf("value %d overflows int32", v)
	}
	return int32(v), nil
}

// closeResponse drains and closes an HTTP response body. It mirrors
// the v6 package's closeResponse helper.
func closeResponse(res *http.Response, rerr *error) {
	if res == nil {
		return
	}
	_, _ = io.Copy(io.Discard, res.Body)
	if err := res.Body.Close(); err != nil && *rerr == nil {
		*rerr = err
	}
}

View on GitHub (pinned to 01ffac6f24)