Android’s threading rules require Looper.prepare() before creating any Handler inside a worker thread. If you’ve ever seen the error “Can’t create handler inside thread that has not called Looper.prepare”, you know it stops your app dead in its tracks. This error is common when you try to use a Handler on a background thread without first setting up a Looper.
The message is clear: Android needs a message loop (Looper) to process Handler tasks. Without it, the system can’t queue or execute your code properly. Let’s break down why this happens and how to fix it.
What Does “Can’t Create Handler Inside Thread That Has Not Called Looper.prepare” Mean?
In Android, every thread that uses a Handler must have a Looper. The main thread (UI thread) already has one set up automatically. But when you create a new thread, you must call Looper.prepare() before creating any Handler. If you skip this step, Android throws the “Can’t create handler inside thread that has not called Looper.prepare” exception.
Think of Looper as a mailroom for your thread. It receives messages and delivers them to the Handler. Without a mailroom, messages have nowhere to go, and the system crashes.
Why Does Android Enforce This Rule?
Android’s architecture is built around message-driven concurrency. The Looper class manages a message queue for a thread. When you create a Handler, it binds to the thread’s Looper. If no Looper exists, the Handler can’t function. This design keeps UI updates safe and prevents race conditions.
Here’s what happens step by step:
- You create a new thread (like new Thread(new Runnable())).
- Inside that thread, you try to create a Handler.
- Android checks if Looper.prepare() was called on this thread.
- If not, it throws the error and your app crashes.
Common Scenarios That Trigger This Error
You’ll see this error in several situations. Knowing them helps you avoid the problem from the start.
1. Creating A Handler Inside A Runnable
This is the most common case. You write code like this:
new Thread(new Runnable() {
@Override
public void run() {
Handler handler = new Handler();
// This line throws the error
}
}).start();The Runnable runs on a background thread. That thread has no Looper, so the Handler creation fails.
2. Using Handlers In AsyncTask Or ThreadPool
AsyncTask and thread pools also run on worker threads. If you try to create a Handler inside their doInBackground() or run() methods, you get the same error. The thread doesn’t have a Looper by default.
3. Posting To A Handler From A Background Thread
Sometimes you create a Handler on the main thread but try to post to it from a background thread. That works fine. But if you create the Handler on the background thread itself, you need Looper.prepare() first.
How To Fix “Can’t Create Handler Inside Thread That Has Not Called Looper.prepare”
You have several solutions. Choose the one that fits your use case best.
Solution 1: Call Looper.prepare() And Looper.loop()
The most direct fix is to call Looper.prepare() before creating the Handler. Then call Looper.loop() to start processing messages.
- Inside your thread, call Looper.prepare().
- Create your Handler.
- Do your work.
- Call Looper.loop() to start the message loop.
Example code:
new Thread(new Runnable() {
@Override
public void run() {
Looper.prepare();
Handler handler = new Handler();
// Now you can use the handler
Looper.loop();
}
}).start();This works but keeps the thread alive forever. You need to quit the looper when done.
Solution 2: Use HandlerThread
HandlerThread is a built-in Android class that handles Looper setup for you. It creates a thread with a Looper ready to go.
- Create a HandlerThread instance.
- Call start() on it.
- Get the Looper from the HandlerThread.
- Pass that Looper to your Handler constructor.
Example:
HandlerThread handlerThread = new HandlerThread("MyThread");
handlerThread.start();
Handler handler = new Handler(handlerThread.getLooper());This is cleaner and safer. You avoid manual Looper management.
Solution 3: Post To The Main Thread Handler
If you don’t need a background Handler, just post your work to the main thread. Use a Handler created on the UI thread.
- Create a Handler in your Activity or Fragment.
- From your background thread, call handler.post(runnable).
- The runnable executes on the main thread.
Example:
Handler mainHandler = new Handler(Looper.getMainLooper());
new Thread(new Runnable() {
@Override
public void run() {
// Do background work
mainHandler.post(new Runnable() {
@Override
public void run() {
// Update UI here
}
});
}
}).start();This avoids creating a Handler on the background thread entirely.
Solution 4: Use RunOnUiThread()
If you’re inside an Activity, use runOnUiThread(). It posts your code to the main thread’s message queue.
runOnUiThread(new Runnable() {
@Override
public void run() {
// Update UI
}
});This is simple and doesn’t require any Handler setup.
Best Practices For Using Handlers And Loopers
Follow these guidelines to avoid the error and write clean code.
Always Create Handlers On The Main Thread For UI Work
UI updates must happen on the main thread. Create your Handler there. Use it to post tasks from background threads.
Use HandlerThread For Background Looper Needs
If you need a background thread with a Looper, use HandlerThread. It’s designed for this purpose. It handles Looper.prepare() and Looper.loop() internally.
Quit The Looper When Done
If you call Looper.loop() manually, remember to quit it. Call looper.quit() or looper.quitSafely() when the thread finishes. Otherwise, the thread stays alive and wastes resources.
Avoid Creating Handlers In Constructors Of Background Tasks
If your class runs on a background thread, don’t create Handlers in the constructor. The constructor runs on the calling thread, not the background thread. Create the Handler inside the run() method after Looper.prepare().
Advanced: Understanding Looper, Handler, And MessageQueue
To truly master this error, understand how these components work together.
Looper
Looper is a class that runs a message loop for a thread. It has a MessageQueue. It continuously checks the queue for new messages and dispatches them. Each thread can have at most one Looper. Call Looper.prepare() to create one, and Looper.loop() to start processing.
Handler
Handler sends and processes messages for a Looper. When you create a Handler, it binds to the Looper of the current thread. You can also pass a specific Looper to the constructor. Handler has two main methods: sendMessage() and post().
MessageQueue
MessageQueue holds the list of messages for a Looper. It’s a queue data structure. Messages are added by Handlers and removed by the Looper. The queue is thread-safe.
How They Work Together
When you call handler.sendMessage(), the Handler puts the message into the Looper’s MessageQueue. The Looper picks it up and calls handleMessage() on the Handler. This all happens on the thread that owns the Looper.
Without a Looper, there’s no queue. The Handler has nowhere to put messages. That’s why Android requires Looper.prepare() before creating a Handler on a worker thread.
Debugging The Error Step By Step
When you see this error, follow these steps to find the cause.
- Check where the Handler is created. Is it inside a Runnable or a background thread method?
- Look at the thread stack trace. It shows which thread threw the error.
- Verify if Looper.prepare() was called before the Handler constructor.
- If you’re using HandlerThread, confirm you called start() before getLooper().
- Check if you’re accidentally creating a Handler in a static initializer or constructor that runs on a background thread.
Most of the time, the fix is simple. Move the Handler creation to the main thread or add Looper.prepare().
Real World Example: Background Image Processing
Let’s say you’re building an app that processes images in the background. You want to show progress on the UI. Here’s the wrong way:
new Thread(new Runnable() {
@Override
public void run() {
// Process image
Handler handler = new Handler(); // Error here
handler.post(new Runnable() {
@Override
public void run() {
// Update progress bar
}
});
}
}).start();This crashes with the “Can’t create handler inside thread that has not called Looper.prepare” error. The fix is to use a Handler from the main thread:
Handler mainHandler = new Handler(Looper.getMainLooper());
new Thread(new Runnable() {
@Override
public void run() {
// Process image
mainHandler.post(new Runnable() {
@Override
public void run() {
// Update progress bar
}
});
}
}).start();Now the Handler is created on the main thread, and posting from the background thread works fine.
When To Use Each Solution
Here’s a quick guide to choose the right approach.
- Simple UI updates: Use runOnUiThread() or a main thread Handler.
- Background thread needs its own Handler: Use HandlerThread.
- Legacy code or special cases: Call Looper.prepare() and Looper.loop() manually.
- One-time background task: Use AsyncTask or coroutines instead of raw threads.
Each solution has its place. HandlerThread is usually the best choice for background Handler needs.
Common Mistakes To Avoid
Even experienced developers make these errors. Watch out for them.
Forgetting To Call Start() On HandlerThread
If you create a HandlerThread but forget to call start(), getLooper() blocks forever. This causes a deadlock. Always call start() before getLooper().
Calling Looper.loop() Without Looper.prepare()
Looper.loop() requires a prepared Looper. If you call it without prepare(), you get a different error. Always call prepare() first.
Creating Multiple Loopers On One Thread
You can only call Looper.prepare() once per thread. Calling it twice throws an exception. Use prepare() only once.
Not Quitting The Looper
If you call Looper.loop() manually, the thread runs forever. Call looper.quit() when you’re done. Otherwise, the thread leaks.
Alternative Approaches In Modern Android
Newer Android APIs reduce the need for manual Handler management.
Kotlin Coroutines
Coroutines handle threading much cleaner. You can use withContext(Dispatchers.Main) to update UI from a background coroutine. No Handlers needed.
lifecycleScope.launch {
withContext(Dispatchers.IO) {
// Background work
}
// Back on main thread automatically
}View.post()
If you have a View reference, use view.post(). It posts a runnable to the main thread’s message queue. This is simpler than creating a Handler.
textView.post(new Runnable() {
@Override
public void run() {
textView.setText("Done");
}
});LiveData And ViewModel
LiveData automatically delivers updates on the main thread. You can post values from background threads without Handlers.
viewModel.liveData.postValue(result);These modern approaches reduce boilerplate and avoid the Looper error entirely.
Testing Your Handler Code
When writing tests, you need to handle Looper setup carefully. Android’s test framework provides tools for this.
Unit Tests
For unit tests, use a mock Looper or Robolectric. Robolectric provides a shadow Looper that works without a real Android environment.
@RunWith(RobolectricTestRunner.class)
public class HandlerTest {
@Test
public void testHandler() {
Looper.prepare();
Handler handler = new Handler();
// Test logic
}
}Instrumentation Tests
In instrumentation tests, the main thread already has a Looper. You can create Handlers normally. For background threads, use HandlerThread in your test setup.
Frequently Asked Questions
Q: Can I Create A Handler In A Service Without Calling Looper.prepare?
If your service runs on the main thread, you don’t need Looper.prepare(). The main thread already has one. But if you start a new thread inside the service, you must call Looper.prepare() before creating a Handler on that thread.
Q: What Happens If I Call Looper.prepare() Twice On The Same Thread?
Android throws a RuntimeException. Each thread can only have one Looper. Call prepare() only once per thread.
Q: Is It Safe To Call Looper.loop() On The Main Thread?
No. The main thread already has a Looper running. Calling loop() again blocks the thread and freezes your app. Only call loop() on background threads you create.
Q: Does HandlerThread Automatically Quit Its Looper?
No. You must call quit() or quitSafely() on the HandlerThread when you’re done. Otherwise, the thread keeps running.
Q: Can I Use A Handler Without A Looper In Any Case?
No. Every Handler needs a Looper. The only exception is if you create a Handler with a null Looper, but that’s not useful. Always ensure a Looper exists.
Conclusion
The “Can’t create handler inside thread that has not called Looper.prepare” error is a common Android pitfall. It happens when you try to create a Handler on a thread without a Looper. The fix is straightforward: call Looper.prepare() first, use HandlerThread, or post to the main thread.
Remember these key points:
- Always create Handlers on threads that have a Looper.
- Use HandlerThread for background Looper needs.
- Post UI updates to the main thread’s Handler.
- Quit your Loopers when done to avoid leaks.
- Modern APIs like coroutines can replace Handlers entirely.
With these solutions, you can handle this error confidently and build smoother Android apps. The error is easy to fix once you understand the underlying threading model. Keep your code clean, use the right tools, and you’ll never see this crash again.