Local Variable Referenced Before Assignment in Python: Causes, Fixes, and Best Practices

Marketing Team

Last Updated: Jul 14, 2026

Total View: 115

Local Variable Referenced Before Assignment in Python

Local Variable Error Breaking Your Python Code?

If Python throws a “local variable referenced before assignment” error, your variable scope or code flow may be the cause. Fix the logic before it leads to repeated runtime failures.

Variable scope debugging
Code flow validation
Function logic fixes
Runtime error handling

Talk to a Tech Consultant

Add us as a preferred source on Google

The “local variable referenced before assignment” error is a common Python issue that occurs when a function tries to access a local variable before a value has been assigned to it. In modern Python versions, this problem is typically raised as an UnboundLocalError.

The error can be confusing because the variable may already exist outside the function, or it may appear to be assigned somewhere inside the code. However, Python follows specific variable scope rules that determine whether a variable is local, global, or nonlocal.

This issue commonly occurs when working with functions, conditional statements, exception handling, loops, global variables, and nested functions. Understanding Python’s scope rules is therefore essential for fixing the problem correctly rather than simply applying a temporary workaround.

In this guide, we will explain what local variable referenced before assignment means, why the error occurs, how to fix it step by step, and the best practices you can follow to prevent similar scope-related errors in Python applications.

What Does “Local Variable Referenced Before Assignment” Mean?

The error means that Python has identified a variable as local to a function, but the program attempts to use that variable before assigning a value to it.

A typical error message looks like this:

UnboundLocalError: local variable 'count' referenced before assignment

In newer Python versions, you may see:

UnboundLocalError: cannot access local variable 'count' where it is not associated with a value

Consider this example:

count = 10
def update_count():
count = count + 1
print(count)
update_count()

At first, this code may appear correct because count already has a value of 10. However, Python raises an UnboundLocalError.

Why?

Because the statement:

count = count + 1

assigns a new value to count inside the function. Python therefore treats count as a local variable throughout the entire function.

However, before assigning the new value, Python attempts to read the local count variable on the right side of the expression:

count + 1

At that point, the local variable has not yet been assigned.

How Does Variable Scope Work in Python?

To properly understand this error, you need to understand how Python searches for variables. Python uses the LEGB rule, which determines the order in which variable names are resolved.

LEGB stands for Local, Enclosing, Global, and Built-in scope. When Python encounters a variable, it searches these scopes in a specific order until it finds the variable.

Local Scope

A local variable is created inside a function and is normally accessible only within that function.

def show_message():
message = "Hello, Python!"
print(message)
show_message()

Here, message exists only inside show_message().

Trying to access it outside the function results in an error:

print(message)

Enclosing Scope

Enclosing scope applies to nested functions. A variable defined in an outer function can be accessed by an inner function.

def outer():
message = "Hello"
def inner():
print(message)
inner()
outer()

The inner() function can access the message variable from the enclosing outer() function.

Global Scope

Variables created outside functions exist in the global scope.

language = "Python"
def show_language():
print(language)
show_language()

The function can read the global variable without any problem.

However, modifying that variable inside the function requires additional handling, which is one of the most common causes of UnboundLocalError.

Built-in Scope

Python also provides built-in names such as:

print()
len()
range()
sum()

These names are available throughout Python programs unless they are overwritten by variables with the same names.

Why Does Local Variable Referenced Before Assignment Occur?

The error can occur in several different programming situations. While global and local variable conflicts are among the most common causes, conditional logic and exception handling can also create the same problem.

Understanding the exact cause helps you choose the appropriate solution without unnecessarily using global or restructuring unrelated code.

Modifying a Global Variable Inside a Function

Consider:

total = 100
def calculate():
total = total + 50
return total

Python considers total a local variable because it is assigned inside calculate().

However, the local total does not have a value when Python evaluates:

total + 50

Therefore, the program raises an UnboundLocalError.

Variable Assigned Only Inside an If Statement

Another common cause is assigning a variable only when a specific condition is true.

def check_age(age):
if age >= 18:
status = "Adult"

return status

Calling:
check_age(15)
causes an error.

Since the condition is false, this statement never executes:

status = "Adult"

The function then tries to return a variable that has never been assigned.

Variable Assigned Inside a Try Block

The problem can also occur during exception handling.

def get_number():
try:
result = int("invalid")
except ValueError:
print("Conversion failed")

return result

The conversion fails before result receives a value. The except block handles the ValueError, but the function later attempts to return result.

Since result was never assigned, Python raises an error.

Modifying Variables in Nested Functions

Nested functions can also produce scope-related problems.

def counter():
count = 0
def increase():
count = count + 1
return count
return increase()

The inner function attempts to modify count. Python therefore treats it as local to increase(), even though another count variable exists in the enclosing function.

How to Fix Local Variable Referenced Before Assignment Step by Step?

There is no single fix for every UnboundLocalError. The correct solution depends on whether the variable should be local, global, or shared between nested functions.

The following seven steps provide a practical troubleshooting process for identifying and resolving the problem.

Step 1: Read the Complete Error Message

Start by examining the traceback.

For example:

Traceback (most recent call last):
File "app.py", line 10, in <module>
calculate()
File "app.py", line 7, in calculate
total = total + 50
UnboundLocalError: local variable 'total' referenced before assignment

The traceback identifies both the variable and the line causing the problem.

Do not focus only on the final error message. Check the surrounding function to determine where the variable is assigned and where it is first accessed.

Step 2: Find Every Assignment to the Variable

Search the function for statements that assign a value to the variable.

Assignments may include:

count = 1

as well as:

count += 1

Python treats augmented assignments such as +=, -=, and *= as assignments too.

If the variable is assigned anywhere inside the function, Python will generally treat it as local unless global or nonlocal is explicitly used.

Step 3: Initialize the Variable Before Using It

One of the simplest solutions is to give the variable an initial value.

Incorrect:

def check_age(age):
if age >= 18:
status = "Adult"
return status

Correct:


def check_age(age):
status = "Minor"
if age >= 18:
status = "Adult"

return status

Now status always has a value regardless of whether the condition executes.

Step 4: Use the Global Keyword When Necessary

If you intentionally need to modify a global variable, use global.

count = 10
def update_count():
global count
count = count + 1
print(count)
update_count()

The output is:

The global declaration tells Python that count refers to the variable outside the function.

However, global variables should be used carefully because excessive global state can make applications difficult to test and maintain.

Step 5: Use Nonlocal for Nested Functions

If an inner function needs to modify a variable belonging to its enclosing function, use nonlocal.

def counter():
count = 0
def increase():
nonlocal count
count += 1
return count
return increase()

Here, nonlocal count tells Python to use the variable from the nearest enclosing function scope.

This is different from global, which searches for a variable at the module level.

Step 6: Handle Every Conditional Path

Check whether every possible code path assigns the variable before it is used.

Incorrect:

def get_discount(is_member):
if is_member:
discount = 20
return discount

Better:

def get_discount(is_member):
if is_member:
discount = 20
else:
discount = 0
return discount

The second version ensures that discount always receives a value.

Step 7: Verify Exception Handling Logic

Variables assigned inside try blocks should be handled carefully because an exception may occur before assignment.

Incorrect:

def convert_value(value):

try:

number = int(value)
except ValueError:
print("Invalid number")
return number

Better:

def convert_value(value):

try:

number = int(value)
except ValueError:
number = None
return number

Now the function always returns a defined value.

Different Ways to Fix UnboundLocalError in Python

The correct solution should reflect how the variable is intended to behave. Initializing every variable or adding global everywhere may hide deeper design problems.

The following methods cover the most common solutions.

Initialize Variables Before Conditional Statements

Variables that depend on conditional logic should usually have a sensible default value.

def find_user(users):
selected_user = None
for user in users:
if user["active"]:
selected_user = user
break
return selected_user

Even when no active user is found, selected_user exists and returns None.

Return Values Instead of Modifying Global Variables

Rather than:

count = 0
def increase():
global count
count += 1
Consider:
def increase(count):
return count + 1
count = 0
count = increase(count)

This approach makes the function easier to test, reuse, and understand.

Return Early from Exception Blocks

Instead of defining fallback variables, some functions can return immediately when an error occurs.

def convert_value(value):

try:

return int(value)
except ValueError:
return None

This implementation is concise and eliminates the possibility of accessing an undefined variable later.

Global vs Nonlocal vs Local Variables in Python

Understanding the difference between these variable types is essential when fixing scope-related errors.

Each scope serves a different purpose and should be used based on where the variable is created and modified.

Variable Type	Defined Where?	Accessible From	Modification Method
Local	Inside a function	Same function	Direct assignment
Enclosing	Outer function	Nested function	nonlocal
Global	Module level	Functions in module	global
Built-in	Python environment	Throughout program	Available automatically

Choosing the correct scope can prevent unexpected errors and improve code maintainability.

Common Mistakes That Cause UnboundLocalError

Many UnboundLocalError problems result from small mistakes in control flow or misunderstanding how Python handles assignments.

Recognizing these patterns can significantly reduce debugging time.

Assuming Python Automatically Uses the Global Variable

Developers may expect Python to use a global variable when a local value is unavailable.

However, if Python detects an assignment inside the function, the variable is considered local throughout that function.

Initializing Variables in Only One Branch

Consider:

if condition:
message = "Success"
print(message)

If condition is false, message never exists.

Always ensure variables are initialized across every possible execution path.

Using Global Variables Unnecessarily

Adding global can fix certain errors, but it should not become the default solution.

Functions that depend heavily on global state are harder to test, reuse, and debug. Passing values as arguments and returning results is often a cleaner design.

Ignoring Exceptions Before Assignment

A try block does not guarantee that every statement inside it will execute.

If an exception occurs before a variable assignment, later code may attempt to use an undefined value.

How Moon Technolabs Helps with Python Development and Optimization?

Moon Technolabs helps businesses build, maintain, and optimize Python-based applications using scalable development practices and modern software architectures. From debugging complex backend systems to developing APIs, AI solutions, automation platforms, and cloud applications, our developers focus on writing reliable and maintainable Python code.

Our Python development approach includes clean architecture, efficient error handling, performance optimization, testing, secure coding practices, and scalable deployment strategies. Whether you need to modernize an existing Python application, resolve performance challenges, or build a new digital solution, Moon Technolabs provides end-to-end development support aligned with your technical and business requirements.

Conclusion

The “local variable referenced before assignment” error occurs when Python attempts to access a local variable before a value has been assigned to it. Although the error often appears simple, it can result from several different situations, including global variable conflicts, incomplete conditional statements, exception handling, and nested function scopes.

The most effective way to fix the problem is to identify where Python considers the variable local and then review every possible execution path. Initializing variables before use, returning values instead of modifying global state, using nonlocal correctly, and handling exceptions carefully can resolve most UnboundLocalError problems.

By understanding Python’s LEGB scope rules and following clear variable management practices, developers can prevent these errors and create applications that are easier to debug, test, maintain, and scale.

About Author

Jayanti Katariya is the CEO of Moon Technolabs, a fast-growing IT solutions provider, with 18+ years of experience in the industry. Passionate about developing creative apps from a young age, he pursued an engineering degree to further this interest. Under his leadership, Moon Technolabs has helped numerous brands establish their online presence and he has also launched an invoicing software that assists businesses to streamline their financial operations.