What causes "invalid queue offset: %w" in t8y2/dbx?

Check broker version and proxy usage; this driver expects native broker remoting responses with 'offset' in ExtFields — target the broker port instead of the proxy.

t8y2/dbx · error

invalid queue offset: %w

Error message

invalid queue offset: %w

What it means

queueOffset issues a max/min-offset remoting request and parses the broker's 'offset' ExtField as int64. If the field is missing or non-numeric, strconv.ParseInt fails and the driver wraps that error with 'invalid queue offset'. It indicates a malformed or unexpected broker response rather than a caller mistake.

Source

Thrown at agents/drivers/rocketmq/messages.go:463

	sort.Slice(targets, func(i, j int) bool {
		if targets[i].BrokerName != targets[j].BrokerName {
			return targets[i].BrokerName < targets[j].BrokerName
		}
		return targets[i].QueueID < targets[j].QueueID
	})
	return targets, nil
}

func queueOffset(ctx context.Context, address, topic string, queueID, requestCode int) (int64, error) {
	response, err := invokeRemotingWithClient(ctx, address, remoting.NewRequest(requestCode, map[string]string{
		"topic": topic, "queueId": strconv.Itoa(queueID),
	}))
	if err != nil {
		return 0, err
	}
	offset, err := strconv.ParseInt(response.ExtFields["offset"], 10, 64)
	if err != nil {
		return 0, fmt.Errorf("invalid queue offset: %w", err)
	}
	return offset, nil
}

func messageMap(topic string, message *admin.MessageExt) map[string]any {
	headers := make(map[string]string, len(message.Properties))
	for key, value := range message.Properties {
		headers[key] = value
	}
	row := map[string]any{
		"topic": topic, "messageId": message.MsgId, "partition": message.QueueId,
		"offset": message.QueueOffset, "timestamp": message.StoreTimestamp,
		"key": message.Properties[primitive.PropertyKeys], "tag": message.Properties[primitive.PropertyTags],
		"headers": headers, "payloadBase64": base64.StdEncoding.EncodeToString(message.Body),
	}
	if utf8.Valid(message.Body) {
		row["payloadText"] = string(message.Body)
	}

View on GitHub (pinned to c0390bff16)

Solutions

Check broker version and proxy usage; this driver expects native broker remoting responses with 'offset' in ExtFields — target the broker port instead of the proxy.
Log response.ExtFields on failure to see what the broker actually returned.
Align driver and broker versions so the wire protocol matches.
Verify the request code (max/min offset) is supported by the broker version.
Retry once the broker is healthy; degraded brokers can return malformed responses.

Defensive patterns

Strategy: try-catch

Try / catch

offset, err := peekMessages(params)
if err != nil {
    var numErr *strconv.NumError
    if errors.As(err, &numErr) && strings.Contains(err.Error(), "invalid queue offset") {
        log.Printf("broker returned non-numeric offset (check broker/proxy version): %v", err)
        return fallbackOffsetQuery(topic, queueID) // use stored checkpoint offset
    }
    return err
}

Prevention

Pin driver and broker to compatible RocketMQ versions; avoid mixing proxy (5.x) endpoints with native remoting code paths.
Point the client at the broker listen port, not a proxy, unless the driver explicitly supports proxy mode.
Log response.ExtFields on parse failures to capture what the broker actually sent.
Keep consumer checkpoints so a failed offset lookup can fall back to a known-good offset.

When it happens

Trigger: Calling peekMessages (which resolves the starting offset via queueOffset) when the broker replies with SUCCESS but no 'offset' ExtField, or a non-numeric value — typically from protocol/version drift or a proxy returning a different response shape.

Common situations: Connecting to a RocketMQ 5.x proxy whose responses differ from native broker responses; broker version mismatch putting the offset elsewhere in the response; broker returning an error payload with code 0; intermediary stripping ExtFields.

Related errors

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