Fix "You need to use a Theme.AppCompat theme (or descendant) with this activity" in Android

The Error

Your app crashes at launch — or the moment you open a dialog — and logcat shows this:

java.lang.IllegalStateException: You need to use a Theme.AppCompat theme (or descendant) with this activity.
    at androidx.appcompat.app.AppCompatDelegateImpl.createSubDecor(AppCompatDelegateImpl.java:852)
    at androidx.appcompat.app.AppCompatDelegateImpl.ensureSubDecor(AppCompatDelegateImpl.java:659)
    at androidx.appcompat.app.AppCompatDelegateImpl.setContentView(AppCompatDelegateImpl.java:540)
    at androidx.appcompat.app.AppCompatActivity.setContentView(AppCompatActivity.java:170)
    at com.example.app.MainActivity.onCreate(MainActivity.java:22)

One line explains everything: the theme assigned to your activity doesn't inherit from Theme.AppCompat. That theme is set in AndroidManifest.xml or styles.xml — and right now it's from the wrong family. AppCompatActivity's internal delegate checks for a compatible theme at startup. No compatible theme, no launch.

Why This Happens

AppCompatActivity uses AppCompat's internal delegate to backport Material components and action bar behavior down to API 14. That delegate looks for a Theme.AppCompat ancestor at startup. Assign it a plain system theme — Theme.Holo, android:Theme.Light, Theme.Material — and it throws immediately.

The most common ways this surfaces:

• You extended AppCompatActivity but left the manifest pointing to @android:style/Theme.Light or similar.
• You migrated to AndroidX and updated your Java/Kotlin code, but styles.xml still has the old parent.
• You're building an AlertDialog from the AndroidX library but passed getApplicationContext() — which carries no activity theme.
• A third-party library activity has a theme override in your manifest that points to a non-AppCompat style.

Step-by-Step Fix

Step 1 — Fix your theme in styles.xml

Open res/values/styles.xml. Your app theme must extend a Theme.AppCompat variant:

<!-- WRONG — plain Android theme -->
<style name="AppTheme" parent="android:Theme.Light">
    ...
</style>

<!-- CORRECT — AppCompat theme -->
<style name="AppTheme" parent="Theme.AppCompat.Light.DarkActionBar">
    ...
</style>

Already on Material Design 3? That's fine. Theme.MaterialComponents.* descends from Theme.AppCompat, so it qualifies:

<style name="AppTheme" parent="Theme.MaterialComponents.Light.DarkActionBar">
    ...
</style>

Step 2 — Verify the theme in AndroidManifest.xml

Check both the <application> tag and any per-activity overrides:

<application
    android:theme="@style/AppTheme"
    ... >

    <!-- Per-activity overrides must also point to an AppCompat theme -->
    <activity
        android:name=".SettingsActivity"
        android:theme="@style/AppTheme.Settings" />

</application>

Easy miss: you fixed the app-level theme, but one activity still has android:theme="@android:style/Theme.Dialog". That activity will still crash.

Step 3 — Fix dialog crashes

If the crash happens inside a dialog rather than in onCreate, the culprit is the context you're passing to AlertDialog.Builder. Application context and service context carry no activity theme. Use the activity itself:

// WRONG — applicationContext has no activity theme
new AlertDialog.Builder(getApplicationContext())

// WRONG — Service or BroadcastReceiver context won't work either
new AlertDialog.Builder(context)

// CORRECT — the Activity carries the AppCompat theme
new AlertDialog.Builder(MainActivity.this)

// CORRECT — inside a Fragment
new AlertDialog.Builder(requireActivity())

In Kotlin:

// CORRECT
AlertDialog.Builder(requireActivity())
    .setTitle("Confirm")
    .setMessage("Are you sure?")
    .setPositiveButton("Yes") { _, _ -> /* action */ }
    .show()

Step 4 — Fix crashes from library activities

If the stack trace points to an activity from a third-party SDK, override its theme in your manifest:

<activity
    android:name="com.somelib.SomeActivity"
    android:theme="@style/AppTheme" />

This forces Android to apply your AppCompat-compatible theme to that library activity instead of whatever the SDK declared.

Verify the Fix

• Clean the project: Build → Clean Project in Android Studio, or run ./gradlew clean.
• Rebuild and run on a device or emulator.
• The activity launches without crashing. No IllegalStateException in logcat.
• The layout editor now renders your theme instead of a blank error state.
• Spot-check every activity with a per-activity theme override — open each one to confirm.

Edge Cases and Tips

• Mixed v21 styles: If res/values-v21/styles.xml still has an old parent like android:Theme.Material, Android 5.0+ devices will read that file and crash — even after you fix the base styles.xml. Check every style variant folder.
• NoActionBar layouts: Building a full-screen or toolbar-based UI? Use Theme.AppCompat.Light.NoActionBar (or the MaterialComponents equivalent). Don't disable the action bar in code — set it in the theme from the start.
• Custom View constructors: Inflating a custom view that contains AppCompat widgets? The Context passed to that constructor must come from an AppCompat activity — not getApplicationContext().
• WindowManager overlays: Floating dialogs created with TYPE_APPLICATION_OVERLAY can't use an activity context. Wrap the application context with a theme instead: new ContextThemeWrapper(appContext, R.style.AppTheme).