PcoWSkbVqDnWTu_dm2ix
The Developer Hub is now deprecated and information on this page may no longer be accurate. To see our new and improved documentation, please click here. You can read more about the future of documentation here.
Collapse Sidebar
  1. apireference
  2. gameplay
  3. teleportservice

TeleportInitFailed

TeleportService

This event fires on both the client and the server when a request to teleport from a function such as TeleportService/TeleportAsync fails and the player does not leave the current server. It provides a reason for the failure, as well as all of the information necessary to retry the teleport. If a group teleport fails, the event will fire once per player.

TeleportOptions

The TeleportOptions object provided by this event is not identical to the one passed to the original TeleportService/TeleportAsync call. It is a new object populated with the necessary parameters to retry the teleport and send the player to the exact same destination. This is especially important for facilitating group teleports when they fail.

Original Teleport Type Teleport Data ReservedServerAccessCode ServerInstanceId ShouldReserveServer
Individual player to place Original value None None false
Player(s) to reserved server Original value Original value, or the code generated if ShouldReserveServer was originally true None false
Player(s) to specific server Original value None Original value false
Players to place Original value None Same destination ID as the other players in the original teleport false

See also

For an in-depth guide on teleporting players and properly handling teleport failures, see the Teleporting Between Places article.

Parameters

Name Type Default Description

player

Instance

The Player instance that failed to teleport.

teleportResult

TeleportResult

The reason for the teleport failure.

errorMessage

string

The message provided to the player explaining the teleport failure.

placeId

int64

The original target place ID of the teleport.

teleportOptions

Instance

A TeleportOptions object that can be passed back to TeleportService/TeleportAsync to retry the failed teleport.

Code Samples

Reattempt Failed Teleport

This code sample includes a function that will reattempt a teleport if Roblox servers are busy or an unexpected failure has occurred. It should be ran on the client.

local TeleportService = game:GetService("TeleportService")
local Players = game:GetService("Players")

local localPlayer = Players.LocalPlayer

local function localTeleportWithRetry(placeId, retryTime)
    local connection
    connection = TeleportService.TeleportInitFailed:Connect(function(player, teleportResult, errorMessage)
        if player == localPlayer then
            print("Teleport failed, TeleportResult: "..teleportResult.Name)
            -- check the teleportResult to ensure it is appropriate to retry
            if teleportResult == Enum.TeleportResult.Failiure or teleportResult == Enum.TeleportResult.Flooded then
                -- disconnect the connection
                connection:Disconnect()
                -- retry in retryTime seconds
                delay(retryTime, function()
                    print("Reattempting teleport")
                    TeleportService:Teleport(placeId)
                end)
            end
        end
    end)
    TeleportService:Teleport(placeId)
end

-- usage example:
local placeId = 1818 -- Crossroads
localTeleportWithRetry(placeId, 5)