dianping/cat · error · RuntimeException

Invalid message ID format: %s

Error message

Invalid message ID format: %s

What it means

MessageId.parse throws this RuntimeException when the input string cannot be split into the required four dash-separated parts: domain-ipAddressInHex-hour-index. The parser scans right-to-left expecting exactly three '-' delimiters; if domain or ip stays null, or hour/index remain -1 (including the case where Integer.parseInt fails and throws first), the format is declared invalid. CAT message IDs are conventionally produced as domain-hexip-hour-index (e.g. "mydomain-c0a86401-3600-1"), so any ID not built by MessageId.toString()/CAT itself will fail.

Source

Thrown at cat-core/src/main/java/com/dianping/cat/message/tree/MessageId.java:73

					break;
				case 3:
					hour = Integer.parseInt(messageId.substring(i + 1, end));
					end = i;
					part--;
					break;
				case 2:
					ipAddressInHex = messageId.substring(i + 1, end);
					domain = messageId.substring(0, i);
					part--;
					break;
				default:
					break;
				}
			}
		}

		if (domain == null || ipAddressInHex == null || hour < 0 || index < 0) {
			throw new RuntimeException("Invalid message ID format: " + messageId);
		} else {
			return new MessageId(domain, ipAddressInHex, hour, index);
		}
	}

	@Override
	public boolean equals(Object obj) {
		if (obj instanceof MessageId) {
			MessageId o = (MessageId) obj;

			if (!m_domain.equals(o.m_domain)) {
				return false;
			}

			if (!m_ipAddressInHex.equals(o.m_ipAddressInHex)) {
				return false;
			}

View on GitHub (pinned to e815e74d4c)

Solutions

  1. Ensure the ID has exactly the shape <domain>-<hexIp>-<hour>-<index>, e.g. by generating it with MessageId.toString() or the CAT client itself
  2. Sanitize input before parsing: trim whitespace and strip surrounding quotes/newlines
  3. Validate the shape with a regex such as ^[^-]+-[0-9a-fA-F]+-\d+-\d+$ before calling parse
  4. If integrating cross-language SDKs, normalize their ID format to the Java convention before handing it to MessageId.parse

Example fix

// before
MessageId id = MessageId.parse(rawIdFromHttpHeader);

// after
String raw = rawIdFromHttpHeader == null ? "" : rawIdFromHttpHeader.trim();
if (!raw.matches("^[^-]+-[0-9a-fA-F]+-\\d+-\\d+$")) {
    throw new IllegalArgumentException("Bad message id: " + raw);
}
MessageId id = MessageId.parse(raw);
Defensive patterns

Strategy: validation

Validate before calling

private static final Pattern MESSAGE_ID = Pattern.compile("^[^-]+-[0-9a-fA-F]+-\\d+-\\d+$");

public static boolean isValidMessageId(String id) {
    return id != null && MESSAGE_ID.matcher(id).matches();
}

// use before parse
if (isValidMessageId(raw)) {
    MessageId parsed = MessageId.parse(raw);
}

Type guard

public static boolean isValidMessageId(String id) {
    if (id == null) return false;
    String[] parts = id.split("-");
    if (parts.length != 4) return false;
    try {
        return Integer.parseInt(parts[2]) >= 0 && Integer.parseInt(parts[3]) >= 0;
    } catch (NumberFormatException e) {
        return false;
    }
}

Try / catch

try {
    MessageId id = MessageId.parse(raw);
} catch (RuntimeException e) {
    if (e instanceof NumberFormatException || e.getMessage().startsWith("Invalid message ID format")) {
        // tolerate bad external IDs: skip or generate a fresh one
        logger.warn("Unparseable message id: " + raw);
    } else {
        throw e;
    }
}

Prevention

When it happens

Trigger: Calling MessageId.parse(messageId) with a string that has fewer than three '-' characters, non-numeric hour or index segments (Integer.parseInt throws NumberFormatException first), negative hour/index values, or null/empty strings. Common when parsing IDs received over HTTP headers, from log files, or cross-language SDKs (e.g. go/php) that format the ID differently.

Common situations: Consuming CAT message-tree IDs produced by non-Java SDKs with different separators; truncated IDs copied from logs or HTTP headers; passing a CAT domain name or path instead of the full message ID; trailing whitespace/newline in the ID string read from a file.

Related errors

AI-assisted analysis of dianping/cat@e815e74d4c (2026-08-14). Data as JSON: /api/errors/2ed1c2539ae7a910. Report an issue: GitHub.