XTLS/Xray-core · critical

grid %d has no uniquely decodable clue set

Error message

grid %d has no uniquely decodable clue set

What it means

Thrown by getBasePatterns during base pattern construction: after filtering, at least one grid ended up with zero uniquely decodable clue sets (a set whose packed key appears exactly once across all grids). Uniqueness is required so the decoder can map a received hint tuple back to one byte, so an empty grid aborts table generation.

Source

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

				clueGroup(g, ps[3]),
			}
			groups = sort4(groups)
			key := packKey(groups)
			keys[gi] = key
			groupsByGrid[gi] = groups
			counts[key]++
		}

		for gi, key := range keys {
			if counts[key] == 1 {
				patterns[gi] = append(patterns[gi], groupsByGrid[gi])
			}
		}
	}

	for gi, list := range patterns {
		if len(list) == 0 {
			return nil, fmt.Errorf("grid %d has no uniquely decodable clue set", gi)
		}
	}

	return patterns, nil
}

func clueGroup(g grid, pos byte) byte {
	// 2 bits of value + 4 bits of position.
	return ((g[pos] - 1) << 4) | (pos & 0x0f)
}

func generateAllGrids() []grid {
	grids := make([]grid, 0, 288)
	var g grid

	var dfs func(idx int)
	dfs = func(idx int) {
		if idx == 16 {

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Remove customTable and use the default entropy layout.
2. Update to a version where the layout and pattern generator are consistent.
3. Report the failing pattern upstream, since this is a layout-level defect.

Example fix

// before
"customTable": "xxvvppvv"
// after
"customTable": ""

layout, err := resolveLayout(mode, customTable)
if err == nil {
	_, err = buildTable(password, layout) // dry-run exposes getBasePatterns errors
}
if err != nil && strings.Contains(err.Error(), "uniquely decodable") {
	layout, _ = resolveLayout("prefer_entropy", "")
}

When it happens

Trigger: The cross-grid dedup filter removing every candidate for some grid, which depends only on the layout (not the password). Indicates the current layout/hint encoding leaves some grid without any unique signature.

Common situations: Custom layouts that compress hint information too aggressively; upstream changes to the key packing or clue enumeration. Not password-dependent, so changing the password does not help.

Related errors

• customTable produced empty padding pool
• not enough sudoku grids: %d
• grid %d has no valid clue set
• decode key collision for byte %d and %d
• invalid sudoku ascii mode: %s

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