Introduction

When building an Android project that uses the Room persistence library, you may encounter the warning or error "Schema export directory is not provided to the annotation processor so we cannot export the schema." This happens because Room can generate JSON schema files for each database version, but it needs to know where to write them. Without this configuration, the build either warns you or fails outright depending on your Room version and build settings.

Why Schema Export Matters

Room schema files are JSON representations of your database structure at each version number. They serve two critical purposes. First, they enable Room to auto-generate migration test helpers that verify your migrations transform the database correctly between versions. Second, they provide a version-controlled history of your database schema, making it easy to review structural changes during code review.

Without exported schemas, you lose access to MigrationTestHelper and must manually verify every migration path.

Fixing with KAPT (Kotlin Annotation Processing)

If your project uses KAPT for annotation processing, add the room.schemaLocation argument in your module-level build.gradle.kts file.

1android {
2    defaultConfig {
3        javaCompileOptions {
4            annotationProcessorOptions {
5                arguments += mapOf(
6                    "room.schemaLocation" to "$projectDir/schemas"
7                )
8            }
9        }
10    }
11}

For Groovy-based build.gradle files, the syntax differs slightly.

1android {
2    defaultConfig {
3        javaCompileOptions {
4            annotationProcessorOptions {
5                arguments = ["room.schemaLocation": "$projectDir/schemas".toString()]
6            }
7        }
8    }
9}

Make sure you also have the KAPT plugin applied at the top of your build file.

1plugins {
2    id("kotlin-kapt")
3}
4
5dependencies {
6    kapt("androidx.room:room-compiler:2.6.1")
7}

Fixing with KSP (Kotlin Symbol Processing)

KSP is the recommended annotation processor for Room in modern Android projects because it is faster than KAPT. The configuration uses the ksp block instead.

1plugins {
2    id("com.google.devtools.ksp")
3}
4
5ksp {
6    arg("room.schemaLocation", "$projectDir/schemas")
7}
8
9dependencies {
10    ksp("androidx.room:room-compiler:2.6.1")
11}

Starting with Room 2.6.0 and the Room Gradle Plugin, you can also use the plugin-based configuration.

1plugins {
2    id("androidx.room") version "2.6.1"
3}
4
5room {
6    schemaDirectory("$projectDir/schemas")
7}

This approach is the cleanest option and works with both KSP and KAPT.

Fixing with Java Annotation Processor

For pure Java projects that do not use Kotlin, the annotation processor options are configured through annotationProcessor in the dependencies block combined with the arguments configuration.

1android {
2    defaultConfig {
3        javaCompileOptions {
4            annotationProcessorOptions {
5                arguments = ["room.schemaLocation": "$projectDir/schemas".toString()]
6            }
7        }
8    }
9}
10
11dependencies {
12    annotationProcessor 'androidx.room:room-compiler:2.6.1'
13}

Setting exportSchema on the Database Class

The @Database annotation has an exportSchema parameter that defaults to true. If you have configured the schema location, keep it set to true so Room generates the files.

1@Database(
2    entities = [User::class, Order::class],
3    version = 3,
4    exportSchema = true
5)
6abstract class AppDatabase : RoomDatabase() {
7    abstract fun userDao(): UserDao
8    abstract fun orderDao(): OrderDao
9}

If you intentionally do not want schema exports (for example, in a quick prototype), you can suppress the warning by setting exportSchema = false. However, this is not recommended for production applications because it disables migration testing support.

1@Database(
2    entities = [User::class],
3    version = 1,
4    exportSchema = false
5)
6abstract class AppDatabase : RoomDatabase()

Using Exported Schemas for Migration Testing

Once schema files are generated, you can use them with MigrationTestHelper to write automated migration tests.

1@RunWith(AndroidJUnit4::class)
2class MigrationTest {
3
4    @get:Rule
5    val helper = MigrationTestHelper(
6        InstrumentationRegistry.getInstrumentation(),
7        AppDatabase::class.java
8    )
9
10    @Test
11    fun migrate2To3() {
12        // Create database at version 2
13        helper.createDatabase("test-db", 2).close()
14
15        // Run migration and validate schema
16        helper.runMigrationsAndValidate("test-db", 3, true, MIGRATION_2_3)
17    }
18}

Add the schemas directory as a test asset source so the test runner can find the JSON files.

1android {
2    sourceSets {
3        getByName("androidTest").assets.srcDirs("$projectDir/schemas")
4    }
5}

Common Pitfalls

• Using KAPT config with KSP dependency: If you switched from kapt to ksp for Room but left the schema location in javaCompileOptions, KSP will not pick it up; use the ksp block or Room Gradle Plugin instead.
• Forgetting to commit the schemas directory: The generated JSON files in schemas/ should be committed to version control so that migration tests work for all developers and in CI.
• Mismatched Room compiler and runtime versions: The room-compiler version must match the room-runtime version exactly, or schema generation may produce unexpected results.
• Setting exportSchema to false to silence the warning: This suppresses the message but disables migration testing, leading to potential data loss bugs when database versions change.
• Not adding schemas to androidTest assets: Even with schema files generated, migration tests will fail with "Cannot find the schema file" unless the schemas directory is registered as an asset source for the androidTest source set.

Summary

• The "schema export directory not provided" error is resolved by setting room.schemaLocation in your Gradle configuration matching your annotation processor (KAPT, KSP, or Java AP).
• The Room Gradle Plugin (2.6.0+) provides the cleanest configuration via room { schemaDirectory(...) }.
• Always keep exportSchema = true in production to enable automated migration testing with MigrationTestHelper.
• Commit the generated schemas/ directory to version control and register it as an androidTest asset source.
• Make sure the Room compiler and runtime dependency versions match exactly across your project.