Roblox error tracking installation

PostHog is available for Roblox through Wally or as a model file you import in Studio.

Via Wally, add the dependency to your wally.toml, run wally install, and map the package into ReplicatedStorage:

[dependencies]
PostHog = "posthog/posthog-roblox@0.1.0"

You can also download the latest posthog-roblox.rbxm from the releases page and insert it into ReplicatedStorage in Studio. Either way you should end up with ReplicatedStorage > PostHog.

Make sure HTTP requests are enabled for your experience: Game Settings > Security > Allow HTTP Requests.

Initialize PostHog once from a server Script (for example in ServerScriptService), keeping error capture enabled:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local PostHog = require(ReplicatedStorage:WaitForChild("PostHog"))

PostHog:Init({
    apiKey = "<ph_project_token>",
    host = "https://us.i.posthog.com",
    captureErrors = true,
    errorDebounceSeconds = 1,
})

You can find your project token and instance address in the project settings page in PostHog.

The Roblox SDK captures exceptions automatically by default. On the server it listens to ScriptContext.Error; requiring the module from a LocalScript captures unhandled client errors and relays them to the server.

Captured events include the error message, the stack trace when available, and SDK metadata.

For handled errors, call CaptureException manually with a subject, message, and optional trace and properties:

local ok, err = pcall(function()
    saveGame(player)
end)

if not ok then
    PostHog:CaptureException(player, err, debug.traceback(), {
        flow = "save_game",
    })
end

To disable automatic exception capture:

PostHog:Init({
    apiKey = "<ph_project_token>",
    captureErrors = false,
})

Trigger a test exception and confirm it appears in the Error tracking tab.

PostHog:CaptureException(nil, "Test exception from Roblox", debug.traceback())
PostHog:Flush()

To test automatic capture, raise an unhandled error from a server Script:

error("Automatic test exception from Roblox")