> ## Documentation Index
> Fetch the complete documentation index at: https://simplecloud.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Transfer a player to another server

> Connect an online player to a known server and handle the result

Use `CloudPlayer.connect(...)` when you already know which server the player should join. The method expects the name registered on the player's proxy, such as `lobby-1`—not the server UUID returned by `Server.getServerId()`.

## Transfer the player

Look up the player by UUID, confirm they are online, and connect them to the registered server name:

```java PlayerTransferService.java theme={null}
import app.simplecloud.api.CloudApi;
import app.simplecloud.api.player.CloudPlayer;

import java.util.UUID;
import java.util.concurrent.CompletableFuture;

public final class PlayerTransferService {
    private final CloudApi api;

    public PlayerTransferService(CloudApi api) {
        this.api = api;
    }

    public CompletableFuture<CloudPlayer.ConnectResult> transfer(
        UUID playerId,
        String registeredServerName
    ) {
        return api.player().get(playerId).thenCompose(player -> {
            if (player == null || !player.isOnline()) {
                return CompletableFuture.completedFuture(
                    CloudPlayer.ConnectResult.PLAYER_NOT_FOUND
                );
            }

            return player.connect(registeredServerName);
        });
    }
}
```

Call `transfer(...)` from your command or matchmaking flow and handle the result:

```java theme={null}
transferService.transfer(playerId, "lobby-1")
    .thenAccept(result -> {
        switch (result) {
            case SUCCESS, ALREADY_CONNECTED ->
                logger.info("Player is connected to lobby-1");
            case SERVER_NOT_FOUND ->
                logger.warning("lobby-1 is not registered on the proxy");
            case PLAYER_NOT_FOUND ->
                logger.info("Player is no longer online");
            case CONNECTION_FAILED ->
                logger.warning("Could not connect player to lobby-1");
        }
    })
    .exceptionally(error -> {
        logger.log(Level.WARNING, "Could not transfer player", error);
        return null;
    });
```

This guide returns `PLAYER_NOT_FOUND` when its lookup finds no online player. If the player disconnects after that check, `connect(...)` returns `CONNECTION_FAILED`.

## Connection results

| Result              | Meaning                                                    |
| ------------------- | ---------------------------------------------------------- |
| `SUCCESS`           | The player connected to the destination.                   |
| `ALREADY_CONNECTED` | The player is already connected to the destination.        |
| `SERVER_NOT_FOUND`  | The supplied name is not registered on the player's proxy. |
| `PLAYER_NOT_FOUND`  | This guide's lookup found no online player.                |
| `CONNECTION_FAILED` | The proxy could not complete the connection.               |

If your plugin needs to find an available destination first, see [Route players with autoscaling](/docs/en/developer/guides/server-management).