t8y2/dbx · error

ETCD_NEWKEY_REQUIRED

ETCD_NEWKEY_REQUIRED

Error message

ETCD_NEWKEY_REQUIRED

What it means

rename requires a target key name in the newKey parameter. The driver validates this before touching etcd and fails fast with this sentinel error when newKey is absent or an empty string. No etcd request is made.

Source

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

	}
	return map[string]any{"deleted": int64(1), "revision": longString(revision)}, nil
}

// rename is a non-atomic check-then-set: the v2 API has no transactions, so a
// concurrent writer between the target check and the delete can be lost. The
// protocol exposes this honestly instead of pretending atomicity.
func (s *etcd2Session) rename(params map[string]json.RawMessage) (any, error) {
	client, err := s.activeClient()
	if err != nil {
		return nil, err
	}
	sourceKey, err := keyBytesParam(params)
	if err != nil {
		return nil, err
	}
	newKey := stringOrNull(params, "newKey")
	if newKey == nil || *newKey == "" {
		return nil, errors.New("ETCD_NEWKEY_REQUIRED")
	}
	targetKey := *newKey
	if sourceKey == targetKey {
		return map[string]any{"renamed": true, "revision": nil}, nil
	}

	ctx, cancel := s.beginOperation()
	defer s.endOperation(cancel)
	body, _, err := client.do(ctx, http.MethodGet, v2KeyPath(sourceKey), "", nil)
	if err != nil {
		if isNotFound(err) {
			return nil, errors.New("ETCD_NOT_FOUND: source key does not exist")
		}
		return nil, err
	}
	var source v2KeysResponse
	if err := json.Unmarshal(body, &source); err != nil {
		return nil, err

View on GitHub (pinned to c0390bff16)

Solutions

1. Pass a non-empty newKey string in the rename params, e.g. {"key":"old","newKey":"new"}.
2. Validate newKey at the call site before invoking rename.
3. If you intended a no-op, note rename with source==target returns {renamed:true}; an empty target is still rejected, so guard empty strings upstream.

Example fix

// before
res, err := agent.Handle(ctx, "rename", map[string]any{"key": "old-key"})
// after
res, err := agent.Handle(ctx, "rename", map[string]any{"key": "old-key", "newKey": "new-key"})

newKey, ok := params["newKey"].(string)
if !ok || newKey == "" {
    return errors.New("rename requires a non-empty newKey")
}

if _, err := agent.Handle(ctx, "rename", params); err != nil && strings.Contains(err.Error(), "ETCD_NEWKEY_REQUIRED") {
    // fix params and re-dispatch with a valid newKey
}

When it happens

Trigger: Calling the rename operation without a newKey field, with newKey: null, or with newKey: "" in the params map.

Common situations: A caller copied a put/get params object that only has key/value and forgot to add newKey; a UI or config layer dropped the empty target field; a generic dispatcher forwards user JSON where newKey was never provided.

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
• ETCD_NEWKEY_REQUIRED
• Key is required
• agentSessionId is required
• ETCD_DEFRAG_TARGET_REQUIRED

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