t8y2/dbx · error

Key is required

Error message

Key is required

What it means

keyBytesParam extracts the key from the params map, accepting either keyBytes (an encoded value object) or key (a JSON string). If neither is present — or key is explicitly null — the driver returns this error before any etcd call. Nearly every key operation (get, put, delete, rename, watch, auth roles) funnels through it.

Source

Thrown at agents/drivers/etcd2-go/kv.go:407

	return "\x00"
}

func keyBytesParam(params map[string]json.RawMessage) (string, error) {
	if encoded := rawObject(params, "keyBytes"); encoded != nil {
		value, err := parseValueObject(encoded)
		if err != nil {
			return "", err
		}
		return value, nil
	}
	if raw, ok := params["key"]; ok && raw != nil && string(raw) != "null" {
		var key string
		if err := json.Unmarshal(raw, &key); err != nil {
			return "", err
		}
		return key, nil
	}
	return "", errors.New("Key is required")
}

func rawObject(params map[string]json.RawMessage, key string) map[string]json.RawMessage {
	raw := params[key]
	if len(raw) == 0 || string(raw) == "null" {
		return nil
	}
	var object map[string]json.RawMessage
	if err := json.Unmarshal(raw, &object); err != nil || object == nil {
		return nil
	}
	return object
}

func bytesObject(bytes []byte) map[string]any {
	return map[string]any{
		"encoding": "base64",
		"data":     base64.StdEncoding.EncodeToString(bytes),

View on GitHub (pinned to c0390bff16)

Solutions

1. Include a non-null string key in the params, e.g. {"key":"cfg/foo"}.
2. Alternatively pass keyBytes for binary keys using the driver's value-object encoding.
3. Validate the key at the call site (non-empty string) before dispatching the operation.
4. Check for typos in the param name — it must be exactly "key" or "keyBytes".

Example fix

// before
params := map[string]any{"value": "x"} // key missing
res, err := agent.Handle(ctx, "put", params)
// after
if k, ok := params["key"].(string); !ok || k == "" {
    return errors.New("key must be a non-empty string")
}
res, err := agent.Handle(ctx, "put", params)

func requireKey(params map[string]any) (string, error) {
    k, ok := params["key"].(string)
    if !ok || k == "" {
        return "", errors.New("key must be a non-empty string")
    }
    return k, nil
}

if _, err := agent.Handle(ctx, "get", params); err != nil && strings.Contains(err.Error(), "Key is required") {
    // params lack key/keyBytes; fix construction and re-dispatch
}

When it happens

Trigger: Calling get/put/delete/rename/watchStart/authRolePermission without a key or keyBytes param, or passing key: null / key as a non-string JSON value that fails to unmarshal into a string.

Common situations: Building params dynamically and dropping the key field on an empty variable; sending key as a number or object instead of a string; a UI binding that left the key input empty; copying a params template that uses a different field name.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• user is required
• Key is required
• agentSessionId is required
• ETCD_DEFRAG_TARGET_REQUIRED
• ETCD_NEWKEY_REQUIRED

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