jackc/pgx · error

cannot parse UUID

Error message

cannot parse UUID %v

What it means

Thrown by parseUUID when the input string's length is neither 36 (standard hyphenated form) nor 32 (bare hexadecimal), so it cannot be a UUID before hex decoding is even attempted. It surfaces through Scan and UnmarshalJSON whenever the source string is malformed, truncated, or carries extra decoration such as a urn:uuid: prefix or braces.

Solutions

1. Validate the string is 36 hyphenated or 32 hex characters before calling Scan or UnmarshalJSON
2. Strip decorations such as urn:uuid: prefixes or braces before parsing
3. Use google/uuid's Parse for lenient handling of variant UUID forms

When it happens

Trigger: Thrown at pgtype/uuid.go:43 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of jackc/pgx@ec1a0befd2 (2026-08-04). Data as JSON: /api/errors/4520a31a15de01f7. Report an issue: GitHub.

Appendix: source

Thrown at pgtype/uuid.go:43

	*b = v
	return nil
}

// UUIDValue implements the [UUIDValuer] interface.
func (b UUID) UUIDValue() (UUID, error) {
	return b, nil
}

// parseUUID converts a string UUID in standard form to a byte array.
func parseUUID(src string) (dst [16]byte, err error) {
	switch len(src) {
	case 36:
		src = src[0:8] + src[9:13] + src[14:18] + src[19:23] + src[24:]
	case 32:
		// dashes already stripped, assume valid
	default:
		// assume invalid.
		return dst, fmt.Errorf("cannot parse UUID %v", src)
	}

	buf, err := hex.DecodeString(src)
	if err != nil {
		return dst, err
	}

	copy(dst[:], buf)
	return dst, err
}

// encodeUUID converts a uuid byte array to UUID standard string form.
func encodeUUID(src [16]byte) string {
	var buf [36]byte

	hex.Encode(buf[0:8], src[:4])
	buf[8] = '-'
	hex.Encode(buf[9:13], src[4:6])

View on GitHub (pinned to ec1a0befd2)