Official sources:
\nStart with a reproducible failure and identify whether it occurs on the client, server, or both. Choose a debugging or profiling tool based on that evidence.
\nUse print, warn, and error deliberately:
print for normal diagnostics.warn for recoverable problems you should notice.error for programming errors that should stop execution.Include context in log messages:
\nwarn(string.format(\"[DataStore] Save failed for %d: %s\", userId, tostring(err)))\nAvoid logging secrets, player data, or PII.
\nWrap fallible calls, especially cloud services, HTTP, DataStores, Marketplace:
\nlocal ok, result = pcall(function()\n return someService:DoSomething()\nend)\nif not ok then\n warn(\"DoSomething failed:\", result)\nend\nUse assert for internal invariants that should never fail:
assert(config.MaxSpeed > 0, \"MaxSpeed must be positive\")\nOpen with F9 in-game or in Studio play mode.
Tabs:
\nToggle Client/Server views to see which side emitted output.
\nThe standard Roblox testing framework is TestEZ. It supports nested describe/it blocks, lifecycle hooks, async tests, and a rich matcher API.
TestEZ example:
\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\nlocal TestEZ = require(ReplicatedStorage.DevPackages.TestEZ)\n\nlocal MathUtils = require(ReplicatedStorage.MathUtils)\n\ndescribe(\"MathUtils\", function()\n it(\"clamps values\", function()\n expect(MathUtils.clamp(5, 0, 10)).to.equal(5)\n expect(MathUtils.clamp(-1, 0, 10)).to.equal(0)\n expect(MathUtils.clamp(11, 0, 10)).to.equal(10)\n end)\nend)\n\nTestEZ.TestBootstrap:run({ game.ReplicatedStorage.Tests })\nFor legacy in-Studio tests, TestService:Error(msg) can mark failures visibly in Studio output, but most projects should prefer TestEZ. The scripts folder contains a minimal TestRunner.lua shim only for environments where TestEZ is unavailable.
Use the Luau language server (luau-lsp) or the Luau type checker in Studio to catch errors before runtime.
Best practices:
\nluau-lsp analyze in CI or before committing.--!strict for new modules.Use Studio's built-in debugger for step-through debugging:
\nUse xpcall with debug.traceback to capture full stack traces from failures:
local ok, err = xpcall(function()\n riskyOperation()\nend, debug.traceback)\nif not ok then\n warn(err)\nend\nThis is especially useful at top-level entry points, scheduled callbacks, and connection handlers where pcall alone discards the stack.
Leaked RBXScriptConnection objects are a common source of memory leaks and stale state. Prefer explicit cleanup patterns:
local Maid = require(path.to.Maid)\nlocal maid = Maid.new()\n\nmaid:GiveTask(workspace.ChildAdded:Connect(onChild))\nmaid:GiveTask(RunService.Heartbeat:Connect(onStep))\n\nmaid:Destroy() -- disconnects everything\n:Once() for one-shot event handlers.Instance.Destroying to trigger cleanup when an instance is removed:obj.Destroying:Connect(function()\n cleanup()\nend)\n:Connect() with a matching :Disconnect() or destruction.The task library is more predictable than legacy spawn, delay, and wait:
-- good\ntask.wait(1)\ntask.delay(1, callback)\ntask.spawn(coroutineOrFn)\n\n-- avoid\nspawn(callback)\ndelay(1, callback)\nwait(1)\ntask.defer is useful for yielding to the next resumption cycle without opening a new thread.
local function sanitize(value)\n if typeof(value) == \"Instance\" and value:IsA(\"Player\") then\n return \"Player(\" .. tostring(value.UserId) .. \")\"\n end\n return value\nend\nlocal lastLog = 0\nlocal function throttledLog(message)\n local now = os.clock()\n if now - lastLog > 5 then\n lastLog = now\n warn(message)\n end\nend\nIncorrect network ownership causes jittery physics and replication lag. Visualize ownership and assign it explicitly:
\n-- Server\npart:SetNetworkOwner(player)\n\n-- Client-side visualization (debug only)\nlocal ownershipLabel -- create BillboardGui or use DebugDraw\nUse BasePart:GetNetworkOwner() to inspect ownership. Vehicles and held items should usually be owned by the controlling player.
For retry-safe reads, use bounded retries with exponential backoff and jitter. Do not use this generic loop to replay writes: a failed response can hide a committed write, and independently retried requests can execute out of order. See roblox-datastores for write reconciliation and per-key ordering.
\nlocal function readWithRetry(fn, maxAttempts)\n maxAttempts = maxAttempts or 5\n for attempt = 1, maxAttempts do\n local ok, result = pcall(fn)\n if ok then\n return true, result\n elseif attempt == maxAttempts then\n return false, result\n else\n warn(\"DataStore attempt \" .. attempt .. \" failed; retrying...\")\n task.wait(2 ^ attempt * 0.1 + math.random() * 0.5)\n end\n end\nend\nAlways call DataStores from the server and validate serialization before saving.
\nUse the Developer Console Memory tab or Scene Analysis to compare snapshots:
\nOpen with Ctrl+F6 (⌘+F6) in Studio or the desktop client.
Use it to:
\ndebug.profilebegin/debug.profileend.Key colors:
\nAvailable in Studio under Window → Performance Summary → Scene Analysis.
\nViews:
\nScene Analysis is a Studio UI tool; there is no public SceneAnalysisService API.
Records CPU time per script. Use it when MicroProfiler points to scripts but you need to know which script.
\n| Symptom | \nLikely causes | \n
|---|---|
| Script silently fails | \nMissing pcall, error swallowed, wrong script context | \n
| Data not saving | \nDataStore called from client, non-serializable value, no pcall | \n
| Remote not working | \nWrong side, handler not connected, argument mismatch | \n
| Lag spikes | \nPathfinding every frame, too many particles, unbatched loops | \n
| Physics jitter | \nWrong network ownership, assembly splits, conflicting constraints | \n
| NPCs stuck | \nBlocked path not recomputed, bad agent params, streaming issues | \n
| UI doesn't update | \nProperty not replicated, wrong parent, layout order | \n
| Memory grows forever | \nLeaked connections, unparented instances, cached assets | \n
Shift+F3 in-game for network debug stats.Measure load time:
\nlocal start = os.clock()\ngame.Loaded:Connect(function()\n print(\"Loaded in\", os.clock() - start)\nend)\nEnable Print Join Size Breakdown in Studio Settings → Network to see the largest replicated instances.
\nscripts/TestRunner.lua: a minimal TestEZ fallback with nested suites, lifecycle hooks, matchers, async support, and TestService integration.scripts/Logger.lua: a structured logger with level filtering and guarded formatting.scripts/DebugDraw.lua: utility for drawing rays, points, and boxes in 3D for visual debugging.