6.2.1 Common scripting errors

Understanding Common Scripting Errors

Roblox scripting often fails in the same predictable ways. Learning to recognize these patterns is the fastest way to debug your games. In this chapter you will focus on the most frequent Lua and Roblox specific mistakes, how they appear in the Output window, and how to fix or prevent them.

Typos and Misspelled Names

One of the simplest but most common errors is a spelling mistake in variable names, services, or object names. Lua is case sensitive, so Health, health, and HEALTH are all different identifiers.

You might see an error like:

Workspace.Script:5: attempt to index nil with 'Value'

This often means you wrote something like:

local leaderstats = player.LeaderStats

when the actual folder is named leaderstats. Since player.LeaderStats does not exist, it returns nil, and then trying to use .Value on nil causes an error.

To avoid this, always double check capitalization, and use the Explorer to confirm the exact names of objects. You can also copy and paste names from the Properties window to reduce mistakes.

Nil Values and "Attempt to Index Nil"

In Roblox scripting, nil means "no value" or "does not exist". Many runtime errors come from trying to use nil as if it was a table, instance, or number.

A very common error is:

Script:10: attempt to index nil with 'Parent'

which usually comes from code like:

local character = player.Character
character.Parent = workspace

If player.Character is not ready yet, character becomes nil and the next line fails. This type of problem often happens when code runs too early.

Typical fixes include checking for nil before using a variable, or waiting until an object exists:

local character = player.Character or player.CharacterAdded:Wait()
character.Parent = workspace

Whenever you see "attempt to index nil", look for the value on the left side of a dot, such as something.X. That "something" is probably nil.

Wrong Parent or Missing Object in the Hierarchy

In Roblox, many scripts break because they assume an object is in a specific place in the hierarchy, but it is not.

For example, if you write:

local button = script.Parent.TextButton

but in the Explorer the button is named PlayButton, your button variable will become nil. Accessing button.Text later will throw a nil error.

Similar problems happen when you use WaitForChild incorrectly:

local tool = script.Parent:WaitForChild("Sword")

If the child is named "SwordTool" instead of "Sword", this call will yield forever, and your script will appear to stop.

Always confirm:

1. The exact name matches the code.
2. The object is a direct child if you use Parent:WaitForChild.
3. You updated references if you renamed objects in Explorer.

Whenever a script does nothing and does not show an error, suspect a WaitForChild waiting on the wrong name.

Incorrect Use of `local` and Scope Problems

Variables in Lua can be either global or local. A very common beginner mistake is to accidentally create or use a global variable instead of a local one.

If you forget the local keyword:

coins = 0

you have created a global variable named coins. Later, some other script can set coins to something else, which can cause difficult bugs.

You can also run into scope errors, where a variable only exists inside a function or a block, but you try to use it outside:

if player then
    local message = "Hello"
end
print(message)  -- error: message is nil

To avoid this, declare variables with local at the top of the scope where you plan to use them:

local message
if player then
    message = "Hello"
end
print(message)

Type Errors and Arithmetic on Non Numbers

Lua is flexible, but arithmetic operations still require numbers. A common scripting error is trying to add or subtract values that are not numbers.

Typical Output message:

Script:12: attempt to perform arithmetic (add) on string and number

This often happens with string values in StringValue objects, user input from a TextBox, or values you read from the DataStore as strings.

For example:

local value = scoreValue.Value      -- "10" as a string
local result = value + 5            -- error

You can convert strings to numbers using tonumber:

local value = tonumber(scoreValue.Value) or 0
local result = value + 5

Also, avoid assuming a property type. Check if a value is a NumberValue or StringValue in the Explorer, and choose the correct type for arithmetic.

Using `:` vs `.` Incorrectly

Roblox uses methods and properties. Methods must be called with :, and properties are accessed with .. Mixing these up is a frequent error.

You might see:

Script:8: attempt to call a nil value

Common causes:

player.Kick("Reason")    -- incorrect

The correct call is:

player:Kick("Reason")

Similarly, you should not use : on properties:

part.Anchored:true     -- incorrect and will cause syntax or runtime issues

The correct syntax is:

part.Anchored = true

When you see "attempt to call a nil value", check functions that you call with parentheses. If you used ., switch to : if it is a method, or check that the function actually exists.

Event Connection Mistakes

Working with Roblox events often leads to errors if you connect them incorrectly or use unsupported arguments.

A common script:

button.MouseButton1Click:Connect(onClick())

This is wrong, because onClick() calls the function immediately and passes its result into Connect. The correct pattern is:

button.MouseButton1Click:Connect(onClick)

or, with an anonymous function:

button.MouseButton1Click:Connect(function()
    onClick()
end)

Another frequent issue is using the wrong event for the object. For example, trying to connect MouseButton1Click on a part instead of a GUI button:

part.MouseButton1Click:Connect(...)

This event does not exist on parts, so you will get an error about indexing nil or a missing event. For 3D objects, use ClickDetector and its MouseClick event, or Touched for touch detection.

If your event handler never runs, check that:

1. You are connecting to an event that the object actually has.
2. The event is connected on the server or client where it is meant to run.
3. You did not call the function instead of passing it to Connect.

Wrong Script Type (Script vs LocalScript)

Many Roblox functions and properties only work on the server or the client. Using the wrong script type often creates confusing bugs without clear error messages.

Common examples:

1. Trying to access PlayerGui from a Script running in ServerScriptService.
2. Trying to use DataStoreService from a LocalScript.
3. Trying to create leaderstats from a LocalScript.

The script might run but nothing visible happens. Sometimes you get a security error in the Output, like:

DataStore request was from client. DataStore can only be accessed from server.

To avoid this, always remember:

• Use Script for server side work such as DataStore, leaderstats, and game logic that must be secure.
• Use LocalScript for player specific UI and client side visuals.

If a script that touches UI does nothing, check that it is a LocalScript and that it is placed in a valid location, such as StarterGui, StarterPlayerScripts, or inside a GUI object.

Infinite Loops and Yielding Problems

Loops are powerful, but writing them incorrectly can freeze your script or create performance issues.

A classic mistake is a while true do loop with no wait:

while true do
    part.CFrame = part.CFrame
end

This loop never yields. It runs every frame without giving Roblox a chance to update, which can freeze the game or make it unusable.

Always include a task.wait() or wait() in infinite or long running loops:

while true do
    part.CFrame = part.CFrame
    task.wait(0.1)
end

Another issue is waiting inside an event handler in a way that blocks other connections, such as doing long loops or long waits within server events that might run frequently. It is often better to use shorter waits and avoid heavy logic inside events.

If your script seems to stop at some line and never reach code after it, look for loops or WaitForChild calls that never complete.

Indexing Tables Incorrectly

Lua tables are flexible, but using them incorrectly can cause errors such as "attempt to index nil" or unexpected nil values.

A common beginner mistake is starting array indices at 0 instead of 1:

local items = {"Sword", "Shield", "Potion"}
print(items[0])   -- nil

Lua arrays typically start at index 1, so you should use items[1] for the first element.

Another issue is mixing key types and assuming order, for example:

local stats = {}
stats["Kills"] = 0
stats[1] = "Player1"

Later, using a for i, v in ipairs(stats) loop will only iterate over numeric keys starting at 1 and stopping at the first nil. The "Kills" key will not appear. For name based data, always access values directly by key:

local kills = stats["Kills"]

When you see a nil table access error, check:

1. If the table itself was created and not nil.
2. If you used the correct key name and type.
3. If you did not accidentally overwrite a table with some other value.

Syntax Errors and Missing Symbols

Syntax errors occur when the code cannot be parsed. These errors appear as soon as you run the game, and often point to the right line or near it. Typical messages include:

Script:12: 'end' expected (to close 'function' at line 5) near <eof>

This usually means you forgot an end for an if, for, while, or function block. Another case:

Script:8: expected ')' near 'then'

In this case, there is probably a missing closing parenthesis before then in an if statement.

To fix syntax errors:

1. Check your pairs of if and end, and function and end.
2. Check all parentheses and quotation marks for proper opening and closing.
3. Fix the first syntax error in the Output before worrying about later ones. Often one small mistake causes many reported errors.

Reading the line number and the section of code shown in the error is the fastest way to spot the missing symbol.

Trying to Access Server Only APIs from the Client

Some Roblox APIs are restricted to the server. Attempting to use them in a LocalScript gives security or permission errors rather than typical Lua errors.

For example, using DataStoreService in a LocalScript:

local DataStoreService = game:GetService("DataStoreService")

will produce messages like:

DataStore request was from client. DataStore can only be accessed from server.

Similarly, creating or modifying values in ServerStorage from a LocalScript is not allowed, because the client cannot access ServerStorage.

If you need to communicate between client and server, use RemoteEvent or RemoteFunction. The server script can then safely use server only APIs.

When you see a permissions related message rather than a typical "nil" or syntax error, check whether you are using a server only feature in a client context.

Misusing `wait`, `spawn`, and Yields

Older Roblox tutorials often use wait and spawn. These functions can create tricky timing bugs when combined with other code.

A typical problem is assuming that code after spawn will wait until the spawned function finishes. In reality, spawn starts the function separately, and the calling code continues immediately:

spawn(function()
    part.Transparency = 1
    wait(5)
    part.Transparency = 0
end)
print("This prints right away")

If you expect print to run after 5 seconds, the script will not behave as you think. You should use task.spawn and plan for asynchronous behavior, or restructure code to use events and clear timing logic.

Another problem is relying on wait() for precise timing or for important logic. wait() is not exact and can be delayed. For smoother and more predictable behavior, use task.wait() and avoid long wait chains for important game logic.

If your code runs in a strange order, or something appears too early or too late, look at where you use wait, spawn, and other yielding functions.

Putting It All Together While Debugging

When you encounter a scripting error, the Output window will give you a clue. Most errors relate to one of these themes: spelling mistakes, nil values, wrong script type, incorrect event usage, table indexing mistakes, or syntax issues.

A simple debugging pattern when you see an error is:

1. Read the error message and note the line number.
2. Look at the object or variable on that line and ask "Could this be nil?"
3. Check the hierarchy and spelling in the Explorer.
4. Add temporary print statements to confirm what values your variables hold.
5. Fix the first error in the Output before chasing later ones.

As you practice, you will begin to recognize these common patterns instantly. That recognition will turn frustrating crashes into quick, systematic fixes, and make your Roblox development much smoother.