skip to content

A Room 3.0 events app marks its attendee-ids converter @ProvidedColumnTypeConverter and now crashes building the database; what is wrong, and how do you fix it?

level: seniorimportance: should knowfreq 28%

answer

  1. Room no longer creates the instance
  2. checked when build() runs
  3. IllegalArgumentException naming the DAO
  4. the test builder too

basics

~10 s

A @ProvidedColumnTypeConverter class must be supplied through addColumnTypeConverter(); without it, build() throws IllegalArgumentException saying a required column type converter is missing. Add the instance to every builder, including test builders.

solid answer

~40 s

Marking the class `@ProvidedColumnTypeConverter` tells Room not to create it, so the app must pass an instance with `RoomDatabase.Builder.addColumnTypeConverter()`. Room checks this in `build()`, when the database's `init()` validates converters: if no passed instance matches a required class, it throws `IllegalArgumentException` with "A required column type converter (...) for ... is missing in the database configuration", naming the converter and the DAO. The fix is to add the instance, and to do the same in every other builder, especially `inMemoryDatabaseBuilder` in tests. The reverse also throws: an instance nothing needs, such as an unannotated class or the same class added twice, fails with "Unexpected column type converter". In Room 2.x it is `@ProvidedTypeConverter` with `addTypeConverter()`.

code

kotlin · 25 lines
kotlin
import android.content.Context
import androidx.room3.ColumnTypeConverter
import androidx.room3.ProvidedColumnTypeConverter
import androidx.room3.Room
import androidx.sqlite.driver.bundled.BundledSQLiteDriver
import kotlinx.serialization.builtins.ListSerializer
import kotlinx.serialization.builtins.serializer
import kotlinx.serialization.json.Json

@ProvidedColumnTypeConverter
class AttendeeIdsConverter(private val json: Json) {
    private val serializer = ListSerializer(Long.serializer())

    @ColumnTypeConverter
    fun toText(ids: List<Long>): String = json.encodeToString(serializer, ids)

    @ColumnTypeConverter
    fun fromText(text: String): List<Long> = json.decodeFromString(serializer, text)
}

fun buildEventDatabase(context: Context, json: Json): EventDatabase =
    Room.databaseBuilder<EventDatabase>(context, "events.db")
        .setDriver(BundledSQLiteDriver())
        .addColumnTypeConverter(AttendeeIdsConverter(json))
        .build()

go deeper

for a junior

Remember that a provided converter needs an instance passed to the database builder.

for a middle

Explain why provided converters exist and which builder call supplies one in each Room major.

for a senior

Diagnose both build-time errors, missing and unexpected converter, from the message, including the test-builder and duplicate-instance cases.

for a principal

Set the rule that one factory or module builds the database, and that only converters with real dependencies are provided.

## What a provided converter is Normally **Room instantiates converter classes itself**: an `object` is used as is, and for an ordinary class Room creates the instance. That breaks down when a converter needs something from outside, such as a configured JSON instance, a clock, or a key for encrypting a column. You cannot inject constructor arguments into an instance Room creates. A **provided converter** solves that. You annotate the class with `@ProvidedColumnTypeConverter` (Room 2.x: `@ProvidedTypeConverter`), keep listing it in `@ColumnTypeConverters` as usual, and hand Room a ready-made instance with `RoomDatabase.Builder.addColumnTypeConverter()` (Room 2.x: `addTypeConverter()`). Room then uses your instance instead of creating one. ## Why the app crashes at build() The annotation is a promise that the instance will arrive. Room checks the promise when the database is **built**, not when the code compiles: 1. The generated database class reports which provided converter classes each DAO needs. 2. `build()` calls the database's `init()`, which runs the converter validation. 3. For every required class, Room looks through the instances passed to the builder. 4. If none is an instance of that class, it throws an **`IllegalArgumentException`**: *"A required column type converter (…AttendeeIdsConverter) for …EventDao is missing in the database configuration."* So the scenario is almost always a builder that never calls `addColumnTypeConverter()`. The fix is to pass the instance: ```kotlin Room.databaseBuilder<EventDatabase>(context, "events.db") .setDriver(BundledSQLiteDriver()) .addColumnTypeConverter(AttendeeIdsConverter(json)) .build() ``` ## The opposite failure The same validation runs the other way. After matching every required class, Room checks that **every instance you passed was used**. An instance that nothing needs makes `build()` throw an `IllegalArgumentException` too: *"Unexpected column type converter … Annotate ColumnTypeConverter class with @ProvidedColumnTypeConverter annotation or remove this converter from the builder."* That happens when: - the class is missing `@ProvidedColumnTypeConverter`, so Room creates its own instance and ignores yours; - the class is not registered in any `@ColumnTypeConverters` that a used type reaches; - the same converter class is added twice: Room matches the most recently added instance and the earlier one is left unused. ## Where it bites in practice | Situation | Symptom | Fix | |---|---|---| | production builder forgot the instance | crash as soon as the database is built | add `addColumnTypeConverter()` | | an instrumented test uses `inMemoryDatabaseBuilder` | tests crash while the app works | the test builder needs the same call | | converter changed to an `object` without the annotation, but still added | "Unexpected column type converter" | remove the builder call or keep it a provided class | | two modules each add the converter | "Unexpected column type converter" | build the database in one place | The test case is the most common in teams: the in-memory builder goes through the same `build()` and the same validation as the app's builder. ## Reading the failure quickly When the crash arrives from a test run or a bug report: 1. Read which message it is. *Missing* means an instance was never passed; *Unexpected* means one was passed that nothing claims. 2. For *missing*, find every place that calls `build()` for this database class: the app's factory, test rules, preview or benchmark helpers. 3. For *unexpected*, check the converter class for `@ProvidedColumnTypeConverter` and for registration in `@ColumnTypeConverters`, then look for a second `addColumnTypeConverter()` call with the same class. ## Production judgment - **Build the database in one place.** A single factory or dependency-injection module that creates the `RoomDatabase` keeps the converter list in one spot; the injection setup itself belongs with Hilt. - **Use a provided converter only when there is a real dependency.** A stateless converter as an `object` needs no builder wiring and cannot fail this way. - **Keep the dependency stable.** The instance lives as long as the database; if the dependency changes its output format, the stored column's meaning changes with it, which is a migration, not a configuration tweak. - **Read the message.** It names both the converter class and the DAO that needs it, which is usually enough to find the builder that is missing the call. In Room 2.x the error texts say *type converter* and *@ProvidedTypeConverter* instead, and the validation logic is the same.

  • Why would you make a converter provided at all instead of an object?
    Because it needs a dependency Room cannot create: a configured JSON instance shared with the network layer, a clock, or a key for encrypting a column. A provided instance also lets tests pass a fake. A stateless converter should stay an `object`, which needs no builder call and cannot fail this validation.
  • What happens if the same provided converter class is added to the builder twice?
    Room matches each required class against the most recently added instance, so the earlier one is never used. The final check then finds an unused instance and `build()` throws `IllegalArgumentException` with "Unexpected column type converter". It usually means two modules both configure the database; build it in one place.

  • A missing provided converter is reported by Room's compiler
  • Room falls back to creating the converter if none is passed
  • Passing an extra converter instance to the builder is harmless
  • In-memory test databases skip Room's converter validation
  • Provided converters no longer need registering with @ColumnTypeConverters

Assumes Room 3.0 (androidx.room3) names; Room 2.8.5 runs the same build-time validation with @ProvidedTypeConverter and addTypeConverter().