XTLS/Xray-core · critical

not enough sudoku grids: %d

Error message

not enough sudoku grids: %d

What it means

Thrown by buildTable when getBasePatterns returns fewer than 256 sudoku grid pattern sets. The encoding maps every byte value 0-255 to a distinct grid, so fewer than 256 grids makes the scheme impossible. This is an internal invariant of the sudoku generator, not a user config error.

Source

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

	return &byteLayout{
		hintMask:    xMask,
		hintValue:   xMask,
		padMarker:   padding[0],
		paddingPool: padding,
		encodeHint:  encodeGroup,
		encodeGroup: encodeGroup,
		decodeGroup: decodeGroup,
	}, nil
}

func buildTable(password string, layout *byteLayout) (*table, error) {
	patterns, err := getBasePatterns()
	if err != nil {
		return nil, err
	}
	if len(patterns) < 256 {
		return nil, fmt.Errorf("not enough sudoku grids: %d", len(patterns))
	}

	order := make([]int, len(patterns))
	for i := range order {
		order[i] = i
	}

	hash := sha256.Sum256([]byte(password))
	seed := int64(binary.BigEndian.Uint64(hash[:8]))
	rng := rand.New(rand.NewSource(seed))
	rng.Shuffle(len(order), func(i, j int) {
		order[i], order[j] = order[j], order[i]
	})

	t := &table{
		decode: make(map[uint32]byte, 1<<16),
		layout: layout,
	}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Update to a consistent version of the finalmask transport (generator and table code must match).
2. Check available memory in the running container/host; grid generation is memory-heavy.
3. If reproducible on a stock build, report it upstream with the exact version.

if _, err := newTable(cfg); err != nil {
	if strings.Contains(err.Error(), "not enough sudoku grids") {
		log.Fatal("transport build invariant broken; update to a consistent release")
	}
	return err
}

When it happens

Trigger: getBasePatterns failing to enumerate enough valid grids, e.g. after a change to grid generation or clue-set filtering. Also possible if grid enumeration is truncated by memory limits in constrained environments.

Common situations: Running a modified or older build where the grid generator differs from the layout code; extremely memory-constrained containers where grid generation silently yields partial results; essentially never seen on a stock build.

Related errors

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

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