t8y2/dbx · error

ETCD_DEFRAG_TARGET_REQUIRED

ETCD_DEFRAG_TARGET_REQUIRED

Error message

ETCD_DEFRAG_TARGET_REQUIRED: at least one endpoint is required

What it means

defrag collects the target endpoints from params (top-level endpoints and/or per-target entries); if after filtering nothing valid remains, it refuses to run and returns ETCD_DEFRAG_TARGET_REQUIRED: at least one endpoint is required. Defragmenting is a per-endpoint maintenance operation, so running it cluster-wide with no explicit targets would be ambiguous and dangerous; the library requires at least one explicit target.

Source

Thrown at agents/drivers/etcd-go/maintenance.go:68

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

func (s *etcdSession) defrag(params map[string]json.RawMessage) (any, error) {
	var targets []string
	if raw := params["endpoints"]; len(raw) > 0 && string(raw) != "null" {
		var list []string
		if jsonUnmarshal(raw, &list) == nil {
			for _, endpoint := range list {
				if endpoint != "" && !containsString(targets, endpoint) {
					targets = append(targets, endpoint)
				}
			}
		}
	}
	if len(targets) == 0 {
		return nil, errors.New("ETCD_DEFRAG_TARGET_REQUIRED: at least one endpoint is required")
	}
	client, err := s.activeClient()
	if err != nil {
		return nil, err
	}

	members := []map[string]any{}
	remaining := targets
	for len(remaining) > 0 {
		endpoint, err := nextDefragEndpoint(client, remaining)
		if err != nil {
			return nil, err
		}
		started := time.Now()
		ctx, cancel := context.WithTimeout(context.Background(), rpcTimeoutSeconds*time.Second)
		_, defragErr := client.Maintenance.Defragment(ctx, endpoint)
		cancel()
		durationMs := time.Since(started).Milliseconds()

View on GitHub (pinned to c0390bff16)

Solutions

1. Pass a non-empty "endpoints" array (e.g. ["http://10.0.0.1:2379","http://10.0.0.2:2379"]) in the defrag params.
2. Fix configuration so the endpoints list is populated and free of blank/invalid entries.
3. Validate endpoint list non-empty (and each entry parses as a URL) before dispatching defrag.
4. If you intend all members, explicitly enumerate them rather than relying on an implicit default.

Example fix

// before
agent.call("defrag", {}) // no targets

// after
agent.call("defrag", {"endpoints": ["http://10.0.0.1:2379", "http://10.0.0.2:2379"]})

func validateDefragEndpoints(eps []string) error {
    if len(eps) == 0 {
        return errors.New("defrag requires at least one endpoint")
    }
    for _, e := range eps {
        if strings.TrimSpace(e) == "" {
            return fmt.Errorf("invalid endpoint %q", e)
        }
    }
    return nil
}

When it happens

Trigger: Calling defrag (via handle) with no "endpoints" array, an empty array, or entries that all fail the endpoint filter (e.g. blank strings), so len(targets)==0 at maintenance.go:68. TestDefragRequiresErrors... TestDefragRequiresEndpoints asserts this behavior.

Common situations: Automation that builds the defrag request from config where the endpoints list is empty or unset; YAML/JSON typo ("endpoint" vs "endpoints"); all candidate endpoints filtered out because of whitespace or malformed URLs in configuration.

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_NEWKEY_REQUIRED
• Key is required

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