grafana/k6 · error

archive_size

Error message

archive_size: %w

What it means

Returned by Client.StartLocalExecution (internal/cloudapi/provisioning/api.go:218) when req.ArchiveSize (bytes, int64) exceeds int32 because the SDK's archive_size field is int32. This is the one overflow in this group that real workloads can hit: an archive larger than 2,147,483,647 bytes (~2 GiB) cannot be described to the backend. Note the 0 case is legal (means 'no archive', sent as JSON null), so only >2 GiB archives fail.

Solutions

  1. Check the archive size before starting: if it exceeds 2 GiB, reduce it — remove non-script assets, .k6ignore-style pruning, or restructure so the test reads data from an object store at runtime instead of shipping it in the archive.
  2. If the script is self-contained, run with --no-archive-upload so ArchiveSize is 0 and no upload happens.
  3. Log the size and largest files: 'du -sh' over the script tree / inspect the tarball to find what bloats it.
  4. Guard at the call site (see defense code) so the failure message is actionable before hitting the API.

Example fix

// before
resp, err := c.StartLocalExecution(ctx, id, provisioning.StartLocalExecutionRequest{ArchiveSize: int64(len(archiveBytes))})

// after — fail fast with guidance before calling the API
const maxArchiveBytes = int64(2147483647) // int32 limit
size := int64(len(archiveBytes))
if size > maxArchiveBytes {
	return fmt.Errorf("archive is %d bytes (> 2 GiB limit); remove large assets or use --no-archive-upload", size)
}
resp, err := c.StartLocalExecution(ctx, id, provisioning.StartLocalExecutionRequest{ArchiveSize: size})
Defensive patterns

Strategy: validation

Validate before calling

const maxArchiveBytes = int64(math.MaxInt32) // 2 GiB SDK limit

func validArchiveSize(size int64) bool {
	return size == 0 || size <= maxArchiveBytes // 0 = no archive upload
}

if !validArchiveSize(int64(len(archiveBytes))) {
	return fmt.Errorf("archive is %d bytes (> 2 GiB); prune assets or use --no-archive-upload", len(archiveBytes))
}

Try / catch

if _, err := c.StartLocalExecution(ctx, id, req); err != nil {
	if strings.Contains(err.Error(), "archive_size") && strings.Contains(err.Error(), "overflows int32") {
		// archive too large to describe to the API — shrink it; retrying cannot help
		return errors.New("archive exceeds 2 GiB cloud limit; remove large files or disable archive upload")
	}
}

Prevention

When it happens

Trigger: Running with an archive whose serialized tar exceeds ~2 GiB: huge data files, node_modules-scale directories, or binary assets bundled next to the script, with archive upload enabled.

Common situations: Script directories containing large fixtures/datasets committed for local testing; multi-file monorepos archived wholesale; workflows that never pruned generated artifacts.

Related errors

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

Appendix: source

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

	if err := json.Unmarshal(req.Options, &opts); err != nil {
		return nil, fmt.Errorf("unmarshalling options for SDK: %w", err)
	}

	maxVUs, err := toInt32(req.MaxVUs)
	if err != nil {
		return nil, fmt.Errorf("max_vus: %w", err)
	}
	totalDuration, err := toInt32(req.TotalDuration)
	if err != nil {
		return nil, fmt.Errorf("total_duration: %w", err)
	}

	sdkReq := k6cloud.NewStartLocalExecutionTestRequest(opts, maxVUs, totalDuration)

	if req.ArchiveSize > 0 {
		v, err := toInt32(req.ArchiveSize)
		if err != nil {
			return nil, fmt.Errorf("archive_size: %w", err)
		}
		sdkReq.SetArchiveSize(v)
	} else {
		sdkReq.SetArchiveSizeNil()
	}

	res, hr, err := c.apiClient.ProvisioningAPI.
		StartLocalExecutionTest(c.authCtx(ctx), loadTestID).
		K6IdempotencyKey(hex.EncodeToString(key[:])).
		StartLocalExecutionTestRequest(sdkReq).
		Execute()
	defer closeResponse(hr, &err)

	if hr != nil {
		if respErr := CheckResponse(hr); respErr != nil {
			return nil, respErr
		}
	}

View on GitHub (pinned to 01ffac6f24)