grafana/k6 · error

unmarshalling image format: %w

Error message

unmarshalling image format: %w

What it means

ImageFormat.UnmarshalJSON (used when decoding screenshot options from JSON) requires a JSON string; if the raw bytes are not a valid JSON string (e.g., a number, object, or malformed JSON), encoding/json fails and is wrapped here. Note that an unknown-but-valid string silently maps to the zero value — this error is strictly about JSON structure, not about the format name.

Source

Thrown at internal/js/modules/k6/browser/common/screenshotter.go:66

func ImageIDFromString(format string) (ImageFormat, bool) {
	id, exists := imageFormatToID[format]
	return id, exists
}

// MarshalJSON marshals the enum as a quoted JSON string.
func (f ImageFormat) MarshalJSON() ([]byte, error) {
	buffer := bytes.NewBufferString(`"`)
	buffer.WriteString(imageFormatToString[f])
	buffer.WriteString(`"`)
	return buffer.Bytes(), nil
}

// UnmarshalJSON unmarshals a quoted JSON string to the enum value.
func (f *ImageFormat) UnmarshalJSON(b []byte) error {
	var j string
	err := json.Unmarshal(b, &j)
	if err != nil {
		return fmt.Errorf("unmarshalling image format: %w", err)
	}
	// Note that if the string cannot be found then it will be set to the zero value.
	*f = imageFormatToID[j]
	return nil
}

type screenshotter struct {
	ctx       context.Context
	persister ScreenshotPersister
	logger    *log.Logger
}

func newScreenshotter(
	ctx context.Context,
	sp ScreenshotPersister,
	logger *log.Logger,
) *screenshotter {
	return &screenshotter{ctx, sp, logger}

View on GitHub (pinned to 93accf6570)

Solutions

1. Ensure format is a quoted JSON string, e.g., "format": "png" (or "jpeg")
2. Validate/serialize the options with a JSON encoder instead of string concatenation
3. Reject non-string format values at the config boundary before decoding

Example fix

// before
{"format": png}

// after
{"format": "png"}

const raw = JSON.parse(cfgJson);
if (typeof raw.format !== 'undefined' && typeof raw.format !== 'string') throw new Error('format must be a string');

const isImageFormat = (v) => v === undefined || v === 'png' || v === 'jpeg' || v === 'webp';

try {
  const fmt = JSON.parse(jsonBytes); // or Go: json.Unmarshal into ImageFormat
} catch (e) {
  if (/unmarshalling image format/.test(e.message)) { /* fix JSON quoting, not the value name */ }
  else throw e;
}

When it happens

Trigger: Decoding screenshot configuration JSON where format is unquoted (format: png instead of "png"), a number, or otherwise syntactically invalid JSON. Reached programmatically (Go/embedding or JSON config paths), not through the normal JS page.screenshot options object.

Common situations: Hand-written JSON configs for screenshot options; integrations that template JSON and drop quotes; passing raw user input as option JSON.

Related errors

• clip area is either empty or outside the viewport
• invalid metric type
• invalid value type
• unmarshalling options for SDK: %w
• converting argument '%v': %w

AI-assisted analysis of grafana/k6@93accf6570 (2026-08-15). Data as JSON: /api/errors/712edac9899e2adf. Report an issue: GitHub.