---
read_when: "Trace a symptom to likely causes and a focused fix"
last_reviewed: 2026-06-17
---

# Common bugs and fixes

## Script silently fails

Causes:
- Error before any output; check Developer Console for errors.
- Script in wrong context (server vs client).
- Event handler disconnected or never connected.
- Infinite yield from `WaitForChild` with no timeout.

Fixes:
- Use `instance:WaitForChild("Name", timeout)`.
- Add `print` at key points to trace execution.
- Check script `RunContext` and parent location.
- Use `xpcall` with `debug.traceback` at entry points to capture full stack traces.

## Data not saving

Causes:
- DataStore call from client/LocalScript.
- Non-serializable value (function, metatable, cycle, inf/nan).
- Missing `pcall` around call.
- Studio backend access disabled for a test experience, or enabled against production data.

Fixes:
- Always call DataStores from server `Script`.
- Test serialization with `HttpService:JSONEncode`.
- Wrap every call in `pcall`.
- Do not let Studio sessions access production backend data; use a separate test experience.

## Remote events not working

Causes:
- Handler on wrong side.
- Firing before handler is connected.
- Argument types differ from handler signature.
- Remote instance not replicated yet.

Fixes:
- Define Remotes in `ReplicatedStorage`.
- Connect handlers early.
- Validate argument count and types.

## Lag spikes

Causes:
- Pathfinding every frame.
- Updating UI every frame without throttling.
- Unbatched DataStore operations.
- Spawning many effects/instances at once.

Fixes:
- Throttle expensive work.
- Batch changes.
- Use object pools.
- Profile with MicroProfiler.

## Physics jitter

Causes:
- Conflicting constraints.
- Wrong network ownership.
- Assembly splits from anchoring.
- Parts fighting each other with forces.

Fixes:
- Visualize constraints and ownership.
- Assign vehicle ownership to driver.
- Anchor only root parts of assemblies.
- Tune force limits.

## Memory leaks

Causes:
- `Heartbeat`/`Stepped` connections not disconnected.
- Tables caching instances after removal.
- Animation/Sound objects not cleaned up.
- Circular references with metatables.

Fixes:
- Disconnect connections in cleanup functions.
- Use `Instance.Destroying` or `AncestryChanged` to trigger cleanup.
- Check Scene Analysis → Unparented instances.
- Compare Luau heap snapshots.

## UI not updating

Causes:
- Property change not replicating.
- Layout not recalculating.
- Wrong parent or ZIndex.
- LocalScript not running in expected context.

Fixes:
- Set properties from the correct side.
- Force layout updates with size/position changes.
- Check StarterGui → PlayerGui cloning.

## Pathfinding failures

Causes:
- Agent parameters incompatible with destination.
- Destination beyond 3,000 studs or vertical limits.
- Dynamic obstacle blocking path.
- Node budget exhausted in complex world.

Fixes:
- Validate parameters.
- Recompute on `path.Blocked`.
- Break long paths into segments.
- Simplify complex geometry.

## Leaked event connections

Causes:
- `Heartbeat`/`Stepped` connections never disconnected.
- One-shot connections left connected after firing.
- Cleanup code unreachable on error paths.

Fixes:
- Use a Maid/Janitor-style collector.
- Use `:Once()` for one-shot handlers.
- Disconnect in `Instance.Destroying` or `AncestryChanged` handlers.

## spawn/delay misuse

Causes:
- Legacy `spawn`/`delay`/`wait` resume unpredictably and can defer indefinitely.

Fixes:
- Replace `spawn(fn)` with `task.defer(fn)` or `task.spawn(fn)`.
- Replace `delay(t, fn)` with `task.delay(t, fn)`.
- Replace `wait(t)` with `task.wait(t)`.

## Log spam and leaked secrets

Causes:
- Printing every frame or every event.
- Logging raw player data, identifiers, or API keys.

Fixes:
- Rate-limit logs with a time gate or counter.
- Sanitize values before logging.
- Never commit secrets; load them from secure configuration.

## DataStore throttling and failures

Causes:
- Missing retry on transient errors.
- Calling DataStores from the client.
- Saving non-serializable values.

Fixes:
- Wrap calls with exponential backoff and jitter.
- Validate JSON serialization before saving.
- Always call DataStores from a server `Script`.

## Network ownership issues

Causes:
- Server simulating objects that a player should control.
- Frequent ownership changes.

Fixes:
- Use `BasePart:SetNetworkOwner(player)` for vehicles and held items.
- Visualize ownership in debug builds with `GetNetworkOwner()`.
- Minimize ownership churn.

## Memory snapshot comparison

For a repeatable leak-finding workflow, compare snapshots:

1. Capture a baseline in a stable state.
2. Perform the suspected leak action repeatedly.
3. Return to the stable state and capture again.
4. Compare PlaceMemory, Luau heap, and instance counts.
5. Check Scene Analysis → Unparented instances.

---
read_when: "Inspect logs, breakpoints, stack traces, or runtime state"
last_reviewed: 2026-06-17
---

# Debugging tools

Official guides:
- https://create.roblox.com/docs/en-us/studio/developer-console
- https://create.roblox.com/docs/en-us/performance-optimization/microprofiler
- https://create.roblox.com/docs/en-us/performance-optimization/scene-analysis

## Developer Console

Shortcuts:
- `F9`: open console.
- `/console`: in chat.

### Log tab

Filter by Output, Information, Warning, Error.
Toggle Client/Server to see which side produced output.

### Memory tab

- **PlaceMemory**: breakdown by assets and engine systems.
- **Luau heap**: detailed script allocation snapshots.

### Network tab

- Summary of HTTP and service requests.
- Per-request status, time, URL, response.

### Server Stats tab

- Heartbeat steps per second.
- Average ping/data ping.

## Output window

Studio-only output. Shows print/warn/error from edit-mode scripts.

## MicroProfiler

Shortcuts:
- `Ctrl+F6` (`⌘+F6`): open.
- `Ctrl+P` (`⌘+P`): pause.

Workflow:
1. Identify a frame-time spike.
2. Zoom into the timeline.
3. Find the widest task bar.
4. Cross-reference with the tag table.
5. Add `debug.profilebegin`/`debug.profileend` around suspicious script code.

Custom profiling:

```lua
debug.profilebegin("HeavyLoop")
-- expensive work
debug.profileend()
```

## Scene Analysis

Available in Studio under **Window → Performance Summary → Scene Analysis**.

Useful views:
- **Script memory**: which scripts allocate the most.
- **Unparented instances**: references held by scripts after instances are removed.
- **Instance composition**: total instance counts.
- **Audio/Animation memory**: asset retention.
- **Triangle composition**: rendering cost breakdown.

Scene Analysis is a Studio UI tool only; there is no public runtime API for it.

## Script Profiler

Records per-script CPU cost. Good for finding expensive scripts without manual labeling.

## Network simulation

Studio: `Alt+S` or **Test → Network Simulation**.

Simulate latency, jitter, and packet loss to reproduce multiplayer issues locally.

## Testing modes

- **Play**: local client+server.
- **Play Here**: spawn at camera.
- **Multi-client simulation**: test ownership and replication with multiple local players.

## Studio Debugger

Use Studio's built-in debugger for step-through debugging:
- Set breakpoints by clicking the gutter next to a line number.
- Run in **Play** mode and use the debugger controls to step over, into, or out.
- Inspect the call stack, local variables, and upvalues in the debugger panel.
- The debugger works in both client and server contexts when Studio runs both.

## Luau type checking

Use the Luau language server (`luau-lsp`) or Studio's Luau type checker to catch errors before runtime.

- Add type annotations to module exports and pure functions.
- Enable `--!strict` for new modules.
- Run `luau-lsp analyze` in CI when available.

## xpcall and debug.traceback

Use `xpcall` with `debug.traceback` to capture full stack traces from failures:

```lua
local ok, err = xpcall(riskyOperation, debug.traceback)
if not ok then
    warn(err)
end
```

Prefer `xpcall` at top-level entry points, scheduled callbacks, and connection handlers.

## Visual debugging

Use `DebugDraw` (see scripts) or temporary `Part` instances to visualize:
- Raycast hits
- Hitboxes
- Path waypoints
- Sensor ranges
- Network ownership boundaries

Always clean up debug visuals in production.

---
read_when: "Reproduce latency, jitter, or packet-loss problems in Studio"
last_reviewed: 2026-09-19
---

# Studio network simulation

Official source: https://create.roblox.com/docs/studio/network-simulator

Network Simulator is a Studio beta that affects playtests, not live players. Enable **New Device Simulator** under **File → Beta Features**, restart Studio, and open **Test → Device Simulator → Network**.

- Inbound means server to client; outbound means client to server. Configure latency, jitter, and packet loss independently for each direction.
- Preset selection and numeric edits are staged until **Apply**. Applying updates a running playtest immediately.
- The values add to existing conditions, including real internet latency in Team Test. Inbound and outbound delays both contribute to round-trip ping.
- **Ideal Fiber** adds 8 ms per direction. Set all six controls to zero and apply for a zero-added-impairment comparison. **Reset** stages Ideal Fiber; it does not disable simulation.
- Packet loss is a percentage: `0.50%` means half a percent, not 50%.
- Saved custom presets persist across sessions, but applied values reset after a full Studio restart.

Repeat the same server-confirmed interaction under baseline, Wi-Fi/mobile, and poor-connection conditions. Check immediate local feedback, duplicate submissions, timeouts, stale unreliable updates, and recovery. Change one direction at a time to isolate request versus response delays. Record the preset, playtest mode, and observed result so comparisons remain reproducible.

The toolbar uses the same `NetworkSettings` properties as Studio Settings: `InboundNetworkMinDelayMs`, `OutboundNetworkMinDelayMs`, `InboundNetworkJitterMs`, `OutboundNetworkJitterMs`, `InboundNetworkLossPercent`, and `OutboundNetworkLossPercent`. Consult their security requirements before using them in plugin automation.

---
read_when: "Find CPU, GPU, memory, or load-time bottlenecks"
last_reviewed: 2026-06-17
---

# Performance profiling

Official guide: https://create.roblox.com/docs/en-us/performance-optimization/identify

## Frame time goals

| FPS | Frame time |
| --- | --- |
| 30 | 33.33 ms |
| 60 | 16.67 ms |
| 120 | 8.33 ms |
| 240 | 4.17 ms |

Consistent frame times matter more than average FPS.

## Server heartbeat

Capped at 60 FPS. Check in Developer Console → Server Stats → Heartbeat → Steps Per Sec.
If below 60, use MicroProfiler on the server to find the bottleneck.

## Client frame rate

Use `Shift+F5` in-game for debug stats, or test on a real mobile device.
High-end PCs can hide performance problems due to thermal/power headroom.

## MicroProfiler colors

- **Orange**: worker thread bottleneck (scripts, physics, pathfinding, animations).
- **Blue**: render thread bottleneck (geometry, effects, UI).
- **Red**: GPU wait (complex geometry, large textures, overdrawing).

## Server profiling

1. Join a live or test game with edit permissions.
2. Open Developer Console (`F9`).
3. Switch to **MicroProfiler** tab.
4. Choose Server, set frames and delay.
5. Click **Begin server recording**.
6. Open the saved HTML dump.

## Common bottlenecks

| Area | Typical causes |
| --- | --- |
| Scripts | Loops every frame, unbatched datastore calls, expensive string/table ops |
| Physics | Too many unanchored parts, conflicting constraints, no sleep |
| Rendering | Too many transparent parts, particles, lights, high-poly meshes |
| Memory | Unloaded assets, leaked instances, growing tables |
| Network | Excessive remote traffic, large replication payloads |

## Optimization workflow

1. Measure with MicroProfiler/Scene Analysis.
2. Identify the biggest single cost.
3. Change one thing.
4. Re-measure.
5. Repeat.

## Mobile profiling

1. Open MicroProfiler on mobile from Settings.
2. Note the IP:port displayed.
3. On a dev machine on the same network, open that IP:port in a browser.
4. Capture frames and analyze in the web UI.

## Counters mode and flame graphs

The web MicroProfiler supports:
- **Flame graphs**: aggregated call stacks.
- **Diff flame graphs**: compare two dumps.
- **X-Ray memory**: highlight allocation-heavy frames.

Use these for regressions and long-term tracking.

## Memory snapshot comparison workflow

Use the Developer Console Memory tab and Scene Analysis to find leaks:

1. Enter a stable baseline state (e.g., standing in lobby with no UI open).
2. Capture snapshot A from Developer Console → Memory or Scene Analysis.
3. Perform the suspected leak action (open/close UI, spawn/despawn enemies).
4. Return to the baseline state.
5. Capture snapshot B.
6. Compare:
   - Total PlaceMemory
   - Luau heap by script
   - Instance counts by category
   - Unparented instances in Scene Analysis
7. Investigate categories that did not return to baseline.

---
read_when: "Write unit tests, mock dependencies, or test client-server flows"
last_reviewed: 2026-06-17
---

# Testing patterns

Official guide: https://roblox.github.io/testez/

## TestEZ

The standard Roblox testing framework is [TestEZ](https://github.com/Roblox/testez). It supports nested `describe`/`it` blocks, lifecycle hooks, async tests, and a rich matcher API.

```lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local TestEZ = require(ReplicatedStorage.DevPackages.TestEZ)

TestEZ.TestBootstrap:run({ game.ReplicatedStorage.Tests })
```

## When to write tests

- Pure utility functions (math, formatting, validation).
- Data transformation and serialization logic.
- State machines with deterministic transitions.
- Anything that has broken before and must not break again.

## Test structure with TestEZ

```lua
describe("MathUtils", function()
    local clamp

    beforeEach(function()
        clamp = require(ReplicatedStorage.MathUtils).clamp
    end)

    it("clamps values", function()
        expect(clamp(5, 0, 10)).to.equal(5)
        expect(clamp(-1, 0, 10)).to.equal(0)
        expect(clamp(11, 0, 10)).to.equal(10)
    end)
end)
```

TestEZ matchers include `to.equal`, `to.be.near`, `to.be.a`, `to.throw`, `to.be.ok`, `to.be.truthy`, and more.

## Example async test

```lua
it("loads data asynchronously", function()
    return expect(Promise.resolve(42)).to.equal(42)
end)
```

For tests that return a Promise, TestEZ waits for resolution. See TestEZ documentation for the exact async API.

## Integration vs unit tests

- **Unit tests** run fast and don't need a running game.
- **Integration tests** require services, instances, or network state. Run them in Studio play mode.

## TestService (legacy)

`TestService:Error(msg)` marks a test failure visibly in Studio output. It is useful for simple in-Studio checks, but new projects should prefer TestEZ.

```lua
local TestService = game:GetService("TestService")

local ok, err = pcall(someTest)
if not ok then
    TestService:Error(err)
end
```

## Running tests

- Place TestEZ test scripts under `ReplicatedStorage.Tests` or another discoverable folder.
- Use `TestEZ.TestBootstrap:run({ folder })` from a single entry point.
- For CI-style testing, collect all test modules and run them with a single runner.
- The scripts/TestRunner.lua module is a minimal shim for environments where TestEZ is unavailable.

## Good test habits

- One assertion per behavior.
- Test edge cases (empty tables, nil, huge values).
- Keep tests deterministic; avoid randomness.
- Clean up any instances created during tests.
- Use `beforeEach`/`afterEach` for shared setup and teardown.
- Mock engine services for unit tests instead of relying on the live data model.