t8y2/dbx · error

id must be a positive integer or 0

Error message

id must be a positive integer or 0

What it means

leaseGrant validates the optional requested lease ID before contacting the cluster: after requiring a positive "ttl", it reads "id" with longOrNull and rejects negative values with "id must be a positive integer or 0". etcd requires lease IDs to be positive (or 0/omitted so the server allocates one), so the library enforces this client-side to fail fast.

Source

Thrown at agents/drivers/etcd-go/lease.go:265

		keys = append(keys, bytesObject(key))
	}
	return map[string]any{
		"id":         unsignedLongString(int64(response.ID)),
		"ttl":        response.TTL,
		"grantedTtl": response.GrantedTTL,
		"keys":       keys,
		"truncated":  len(response.Keys) > maxLeaseAttachedKeys,
	}, nil
}

func (s *etcdSession) leaseGrant(params map[string]json.RawMessage) (any, error) {
	ttl, err := requiredPositiveLong(params, "ttl")
	if err != nil {
		return nil, err
	}
	requestedID := longOrNull(params, "id")
	if requestedID != nil && *requestedID < 0 {
		return nil, errors.New("id must be a positive integer or 0")
	}
	client, err := s.activeClient()
	if err != nil {
		return nil, err
	}
	ctx, cancel := s.beginOperation()
	defer s.endOperation(cancel)
	var grantedID clientv3.LeaseID
	var grantedTTL int64
	if requestedID == nil || *requestedID == 0 {
		response, err := client.Lease.Grant(ctx, ttl)
		if err != nil {
			return nil, err
		}
		grantedID = response.ID
		grantedTTL = response.TTL
	} else {
		leaseClient := etcdserverpb.NewLeaseClient(client.ActiveConnection())

View on GitHub (pinned to c0390bff16)

Solutions

1. Pass id as 0 or omit it entirely to let etcd allocate a fresh lease ID.
2. Clamp/reject negative IDs at the call site before invoking leaseGrant.
3. If you need a specific ID, choose a positive integer you know is unused on the cluster.

Example fix

// before
agent.call("lease_grant", {"ttl": 30, "id": -1})

// after: let the server pick an ID
agent.call("lease_grant", {"ttl": 30, "id": 0})

if id < 0 {
    return errors.New("leaseGrant id must be >= 0; use 0 to let the server allocate")
}

When it happens

Trigger: Calling leaseGrant with params {"id": -1, ...} (any negative integer) while "ttl" is a positive value — checked at lease.go:265. Omitting id or passing id=0 is allowed (server assigns an ID).

Common situations: Constructing the id from parsed input where -1 is used as a 'not set' marker; porting code from another system where negative IDs are reserved; arithmetic underflow producing a negative ID.

Understand the failure class

Background: "must be positive", "Invalid value": how libraries reject invalid parameter values (ValueError, ArgumentError, INVALID_PARAMETER_VALUE) — this error's family across 28 libraries.

Related errors

• lease, ttl, and preserveLease cannot be specified together
• ttl must be a positive integer
• ETCD_INVALID_%s
• user is required
• Cannot preserve lease: key does not exist or has no lease

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