What causes "Unsupported value encoding: %s" in t8y2/dbx?

Change the encoding parameter to exactly "utf8" (lowercase) for plain text values.

Unsupported value encoding: %s

Error message

Unsupported value encoding: %s

What it means

parseValueObject decodes etcd values returned by kv operations into human-readable form based on a requested encoding. Only 'base64' (and 'utf8' passthrough) are supported; any other encoding string is rejected with this error. It is a strict input-validation error on the encoding parameter, not a data-corruption error.

Source

Thrown at agents/drivers/etcd-go/kv.go:546

	}
	return base64.StdEncoding.EncodeToString(bytes)
}

func parseValueObject(value map[string]json.RawMessage) (string, error) {
	if value == nil {
		value = map[string]json.RawMessage{}
	}
	encoding := stringOrDefault(value, "encoding", "utf8")
	data := stringOrDefault(value, "data", "")
	if encoding == "base64" {
		decoded, err := base64.StdEncoding.DecodeString(data)
		if err != nil {
			return "", err
		}
		return string(decoded), nil
	}
	if encoding != "utf8" {
		return "", fmt.Errorf("Unsupported value encoding: %s", encoding)
	}
	return data, nil
}

func longString(value int64) string {
	return strconv.FormatInt(value, 10)
}

func unsignedLongString(value int64) string {
	return strconv.FormatUint(uint64(value), 10)
}

func stringOrNull(params map[string]json.RawMessage, key string) *string {
	raw := params[key]
	if len(raw) == 0 || string(raw) == "null" {
		return nil
	}
	var value string

View on GitHub (pinned to c0390bff16)

Solutions

Change the encoding parameter to exactly "utf8" (lowercase) for plain text values.
Use "base64" and base64-encode binary values before sending.
Normalize casing/whitespace on the caller side: strings.ToLower(strings.TrimSpace(encoding)) before sending.
Consult the driver's supported encoding list in kv.go parseValueObject and stick to it; do not invent values like "hex".

Example fix

// before
{"key": "Zm9v", "value": "YmFy", "encoding": "UTF8"}
// after
{"key": "Zm9v", "value": "YmFy", "encoding": "utf8"}

Defensive patterns

Strategy: validation

Validate before calling

func validEncoding(enc string) bool {
	switch strings.ToLower(enc) {
	case "utf8", "base64":
		return true
	}
	return false
}
// if !validEncoding(enc) { return error before calling the driver }

Type guard

func isSupportedEncoding(v any) bool {
	s, ok := v.(string)
	if !ok {
		return false
	}
	return s == "utf8" || s == "base64"
}

Try / catch

value, err := driverPut(req)
if err != nil {
	if strings.HasPrefix(err.Error(), "Unsupported value encoding") {
		// fall back to base64 and re-encode the payload
		req.Encoding = "base64"
		req.Value = base64.StdEncoding.EncodeToString(raw)
		value, err = driverPut(req)
	}
	if err != nil {
		return fmt.Errorf("put failed: %w", err)
	}
}

Prevention

Restrict the encoding input to a validated allowlist in your client API.
Normalize encoding strings (lowercase, trim) before sending.
Default to "base64" for binary payloads and "utf8" for text; never free-form values.
Document supported encodings where the request schema is defined.

When it happens

Trigger: Calling put, keyBytesParam, or any op that flows through parseValueObject with an encoding value other than "base64" or "utf8" (e.g. "hex", "UTF-8", "ascii", "string").

Common situations: Hand-written JSON requests to the kv driver using an intuitive-but-unsupported encoding name like "text" or "string"; case mismatch ("UTF8" vs "utf8"); client SDK versions where encoding param naming changed; copying examples from a different driver that supports hex.

Related errors

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/4e067a4c48ff7bab. Report an issue: GitHub.