XTLS/Xray-core · error

customTable must be 8 chars, got %d

Error message

customTable must be 8 chars, got %d

What it means

Thrown by normalizeCustomTable when the customTable string, after lowercasing, trimming, and removing all spaces, is not exactly 8 characters long. The custom table describes a byte layout with 8 bit-slots, so any other length is rejected before a layout can be built.

Source

Thrown at transport/internet/finalmask/sudoku/table.go:182

	return pMin, pMax
}

func normalizeASCII(mode string) (string, error) {
	switch strings.ToLower(strings.TrimSpace(mode)) {
	case "", "entropy", "prefer_entropy":
		return "prefer_entropy", nil
	case "ascii", "prefer_ascii":
		return "prefer_ascii", nil
	default:
		return "", fmt.Errorf("invalid sudoku ascii mode: %s", mode)
	}
}

func normalizeCustomTable(pattern string) (string, error) {
	cleaned := strings.ToLower(strings.TrimSpace(pattern))
	cleaned = strings.ReplaceAll(cleaned, " ", "")
	if len(cleaned) != 8 {
		return "", fmt.Errorf("customTable must be 8 chars, got %d", len(cleaned))
	}

	var xCount, pCount, vCount int
	for _, ch := range cleaned {
		switch ch {
		case 'x':
			xCount++
		case 'p':
			pCount++
		case 'v':
			vCount++
		default:
			return "", fmt.Errorf("customTable has invalid char %q", ch)
		}
	}
	if xCount != 2 || pCount != 2 || vCount != 4 {
		return "", fmt.Errorf("customTable must contain exactly 2 x, 2 p and 4 v")
	}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Count the letters: the value must contain exactly 8 characters made of x, p, v (spaces allowed but ignored).
2. Use a canonical pattern such as "xxppvvvv".
3. Leave customTable empty to use the default entropy layout instead.

Example fix

// before
"customTable": "xxppvvv"
// after
"customTable": "xxppvvvv"

p := strings.ReplaceAll(strings.ToLower(strings.TrimSpace(cfg.CustomTable)), " ", "")
if p != "" && len(p) != 8 {
	return fmt.Errorf("customTable must be 8 chars after trimming spaces, got %d", len(p))
}

When it happens

Trigger: Configuring customTable with 7 or 9 characters, e.g. "xxppvvv" or "xxppvvvvv". Also triggered by patterns like "xx pp vvvv" (7 letters after space removal) or an empty string where a custom layout is expected.

Common situations: Miscounting the pattern characters when hand-writing the config; copying a pattern with a missing or extra character from docs or chat; assuming spaces count toward the 8 chars (they are stripped before the length check).

Related errors

• invalid sudoku ascii mode: %s
• customTable has invalid char %q
• customTable must contain exactly 2 x, 2 p and 4 v
• customTable produced empty padding pool
• decode key collision for byte %d and %d

AI-assisted analysis of XTLS/Xray-core@7d214f8b09 (2026-08-15). Data as JSON: /api/errors/53425a82bfd72578. Report an issue: GitHub.