XTLS/Xray-core · error

first prefixed padding turn is not client-to-server

Error message

first prefixed padding turn is not client-to-server

What it means

validatePaddingSchedule requires that when firstTurnPrefixLength > 0, the first padding turn flows client-to-server: the prefix bytes were client-sent real record bytes, so the camouflage padding that follows must continue in the same direction. A server-to-client first turn with a prefix is a contradiction.

Source

Thrown at transport/internet/finalmask/xmc/padding.go:81

			}
			continue
		}
		if err := readPaddingTurn(reader, turn, prefixLength); err != nil {
			return fmt.Errorf("read padding turn %d: %w", i, err)
		}
	}
	return nil
}

func validatePaddingSchedule(schedule []paddingTurn, firstTurnPrefixLength int) error {
	if len(schedule) == 0 {
		return fmt.Errorf("empty padding schedule")
	}
	if firstTurnPrefixLength < 0 {
		return fmt.Errorf("negative first turn prefix length: %d", firstTurnPrefixLength)
	}
	if firstTurnPrefixLength > 0 && schedule[0].direction != paddingClientToServer {
		return fmt.Errorf("first prefixed padding turn is not client-to-server")
	}

	for i, turn := range schedule {
		if turn.direction != paddingClientToServer && turn.direction != paddingServerToClient {
			return fmt.Errorf("padding turn %d has invalid direction: %d", i, turn.direction)
		}
		if err := validatePaddingDelayRange(turn.startDelay); err != nil {
			return fmt.Errorf("padding turn %d has an invalid start delay: %w", i, err)
		}
		if err := validatePaddingDelayRange(turn.chunkDelay); err != nil {
			return fmt.Errorf("padding turn %d has an invalid chunk delay: %w", i, err)
		}
		if turn.writeChunkMinLength < 0 || turn.writeChunkLength < turn.writeChunkMinLength || turn.writeChunkLength > maxPaddingChunkLength {
			return fmt.Errorf("padding turn %d has an invalid write chunk range: %d-%d", i, turn.writeChunkMinLength, turn.writeChunkLength)
		}
		if len(turn.variants) > 0 && turn.writeChunkLength != 0 {
			return fmt.Errorf("padding turn %d combines variants with generated write chunks", i)
		}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Make the first turn direction paddingClientToServer whenever the prefix is non-zero
2. Emit schedules from one builder that knows the client perspective rather than hand-editing turn lists
3. Add a schedule round-trip test that validates client and mirrored server schedules together

Example fix

// before
schedule := []paddingTurn{{direction: paddingServerToClient, ...}}

// after
schedule := []paddingTurn{{direction: paddingClientToServer, ...}, {direction: paddingServerToClient, ...}}

if prefix > 0 && schedule[0].direction != paddingClientToServer {
    return fmt.Errorf("schedule invalid for prefixed first turn")
}

func validFirstTurn(s []paddingTurn, prefix int) bool {
    return prefix == 0 || (len(s) > 0 && s[0].direction == paddingClientToServer)
}

When it happens

Trigger: Building a schedule whose first turn has direction paddingServerToClient while passing a positive prefix length; inverting the isClient flag at a call site so directions are mirrored.

Common situations: Forks writing new schedule profiles; copy-paste of a server-perspective schedule into a client code path; tests constructing schedules by hand.

Related errors

• padding turn %d has invalid direction: %d
• padding turn %d combines variants with generated write chunk
• padding turn %d: %w
• unexpected client IP length
• empty padding schedule

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