Fixing 'You Must Annotate Primary Keys with @NonNull' in Android Room: Causes and Solutions

Android Room is a powerful ORM (Object-Relational Mapping) library that simplifies database operations in Android apps. It provides compile-time SQL validation, reduces boilerplate code, and ensures type safety—making it a go-to choice for local data persistence. However, like any tool, Room enforces strict rules to maintain database integrity, and one common roadblock developers face is the error: "You must annotate primary keys with @NonNull".

This error occurs when Room detects a primary key field that could potentially be null, violating the fundamental requirement of primary keys in relational databases (they must uniquely identify rows and cannot be null). In this blog, we’ll dive deep into the causes of this error, explore step-by-step solutions with code examples, and share best practices to avoid it altogether.

Table of Contents#

  1. Understanding the Error
  2. Common Causes of the Error
  3. Step-by-Step Solutions
  4. Practical Code Examples
  5. Best Practices to Avoid the Error
  6. Troubleshooting Tips
  7. Conclusion
  8. References

Understanding the Error#

Before fixing the error, let’s clarify what it means. In relational databases, a primary key is a column (or set of columns) that uniquely identifies each row in a table. By definition, primary keys cannot be null—otherwise, they fail to uniquely identify rows.

Room enforces this rule at compile time to prevent runtime crashes and data corruption. When it detects a primary key field that is nullable (i.e., could be null), it throws the error: "You must annotate primary keys with @NonNull".

This error is not just a warning—it blocks compilation until resolved. Let’s explore why it happens and how to fix it.

Common Causes of the Error#

The error typically stems from one of the following issues in your Room entity classes:

1. Nullable Type for the Primary Key#

The most common cause is using a nullable type (e.g., Long? in Kotlin, Long in Java without @NonNull) for the primary key field.

  • In Kotlin: Nullable types are denoted with a ? (e.g., id: Long?).
  • In Java: Reference types (e.g., Long, Integer) are nullable by default unless marked with @NonNull.

2. Missing @NonNull Annotation#

Even if you use a non-null type, Room may still require the @NonNull annotation for clarity, especially in Java. For example, using long (a primitive, non-null type) in Java does not require @NonNull, but using Long (a nullable reference type) without @NonNull will trigger the error.

3. Composite Primary Keys with Nullable Fields#

If you use a composite primary key (multiple fields to uniquely identify a row), all fields in the composite key must be non-null. A single nullable field in the composite key will cause the error.

4. Incorrect Use of autoGenerate#

When using autoGenerate = true for auto-incrementing primary keys, developers sometimes use nullable types (e.g., id: Long?) assuming Room will handle nulls. However, Room requires the field to be non-null, even with auto-generation.

Step-by-Step Solutions#

Let’s resolve the error by addressing each cause with actionable solutions.

Solution 1: Use Non-Null Types for Primary Keys#

Ensure the primary key field uses a non-null type. In Kotlin, omit the ? suffix; in Java, use primitive types (e.g., long, int) or annotate reference types with @NonNull.

Solution 2: Explicitly Add the @NonNull Annotation#

Always annotate primary keys with @NonNull (from androidx.annotation.NonNull). This makes your intent clear to Room and avoids ambiguity, even for non-null types.

Solution 3: Fix Composite Primary Keys#

For composite primary keys (defined via primaryKeys in @Entity), ensure all fields in the key are non-null and annotated with @NonNull.

Solution 4: Correct autoGenerate Setup#

When using autoGenerate = true, initialize the primary key to a default value (e.g., 0 for numeric keys) to ensure it’s non-null. Room will override this value with the auto-generated ID during insertion.

Practical Code Examples#

Let’s walk through before/after examples to see these solutions in action.

Example 1: Simple Entity with Nullable Primary Key (Kotlin)#

❌ Incorrect (Causes Error)#

import androidx.room.Entity
import androidx.room.PrimaryKey
 
@Entity(tableName = "users")
data class User(
    @PrimaryKey val id: Long?, // Nullable type (`Long?`) triggers error
    val name: String,
    val email: String
)

Why? id: Long? is nullable, violating Room’s primary key non-null requirement.

✅ Correct (Fixed)#

import androidx.room.Entity
import androidx.room.PrimaryKey
import androidx.annotation.NonNull
 
@Entity(tableName = "users")
data class User(
    @PrimaryKey @NonNull val id: Long, // Non-null type + @NonNull
    val name: String,
    val email: String
)

Why? id: Long (non-null) and @NonNull explicitly enforce that id cannot be null.

Example 2: Auto-Generated Primary Key (Kotlin)#

❌ Incorrect (Causes Error)#

@Entity(tableName = "posts")
data class Post(
    @PrimaryKey(autoGenerate = true) val id: Long?, // Nullable with autoGenerate
    val title: String,
    val content: String
)

Why? Even with autoGenerate = true, id: Long? is nullable. Room needs a non-null field to store the generated ID.

✅ Correct (Fixed)#

@Entity(tableName = "posts")
data class Post(
    @PrimaryKey(autoGenerate = true) @NonNull val id: Long = 0L, // Non-null with default 0
    val title: String,
    val content: String
)

Why? id: Long = 0L initializes the field to 0 (non-null). Room replaces 0 with an auto-generated ID during insertion.

Example 3: Java Entity with Nullable Primary Key#

❌ Incorrect (Causes Error)#

import androidx.room.Entity;
import androidx.room.PrimaryKey;
 
@Entity(tableName = "products")
public class Product {
    @PrimaryKey
    private Long id; // Nullable reference type (Long) without @NonNull
    private String name;
    private double price;
 
    // Constructor, getters, setters
    public Product(Long id, String name, double price) {
        this.id = id;
        this.name = name;
        this.price = price;
    }
 
    // Getters and setters...
}

Why? Long id is a nullable reference type. Without @NonNull, Room flags it as a potential null primary key.

✅ Correct (Fixed)#

import androidx.room.Entity;
import androidx.room.PrimaryKey;
import androidx.annotation.NonNull;
 
@Entity(tableName = "products")
public class Product {
    @PrimaryKey
    @NonNull
    private Long id; // Reference type with @NonNull
    private String name;
    private double price;
 
    public Product(@NonNull Long id, String name, double price) {
        this.id = id;
        this.name = name;
        this.price = price;
    }
 
    // Getters and setters...
}

Alternative (Using Primitive Type):

@Entity(tableName = "products")
public class Product {
    @PrimaryKey
    private long id; // Primitive type (non-null, no @NonNull needed)
    private String name;
    private double price;
 
    // Constructor, getters, setters...
}

Example 4: Composite Primary Key#

❌ Incorrect (Causes Error)#

@Entity(
    tableName = "order_items",
    primaryKeys = ["orderId", "productId"] // Composite key
)
data class OrderItem(
    val orderId: Long?, // Nullable field in composite key
    @NonNull val productId: Long,
    val quantity: Int
)

Why? orderId: Long? is nullable, making the composite key invalid.

✅ Correct (Fixed)#

@Entity(
    tableName = "order_items",
    primaryKeys = ["orderId", "productId"]
)
data class OrderItem(
    @NonNull val orderId: Long, // Non-null + @NonNull
    @NonNull val productId: Long, // Non-null + @NonNull
    val quantity: Int
)

Why? All fields in the composite key (orderId and productId) are non-null and annotated with @NonNull.

Best Practices to Avoid the Error#

To prevent the "You must annotate primary keys with @NonNull" error, follow these best practices:

1. Always Use Non-Null Types#

  • Kotlin: Omit ? for primary key fields (e.g., Long instead of Long?).
  • Java: Use primitive types (e.g., long, int) for primary keys, or annotate reference types (e.g., Long) with @NonNull.

2. Explicitly Annotate with @NonNull#

Even for non-null types, adding @NonNull (from androidx.annotation.NonNull) improves readability and avoids ambiguity.

3. Handle Auto-Generated Keys Carefully#

  • Initialize auto-generated keys to a default value (e.g., 0L in Kotlin) to ensure non-nullability.
  • Use autoGenerate = true only for numeric keys (e.g., Long, Int).

4. Validate Composite Keys#

For composite primary keys, verify that all fields are non-null and annotated with @NonNull.

Troubleshooting Tips#

If the error persists after applying fixes:

1. Check for Hidden Nullable Types#

Inspect the primary key field’s type. In Kotlin, ensure there’s no accidental ? suffix. In Java, confirm reference types (e.g., Long) are annotated with @NonNull.

2. Clean and Rebuild Your Project#

Room generates code at compile time. Old generated files may cache the error. Use Build > Clean Project and Build > Rebuild Project to refresh.

3. Verify Composite Key Fields#

If using a composite key, ensure every field listed in primaryKeys is non-null and annotated with @NonNull.

4. Update Room Dependencies#

Outdated Room versions may have bugs. Ensure you’re using the latest stable version in build.gradle:

dependencies {
    def room_version = "2.5.2" // Check for the latest version!
    implementation "androidx.room:room-runtime:$room_version"
    kapt "androidx.room:room-compiler:$room_version"
}

Conclusion#

The "You must annotate primary keys with @NonNull" error in Android Room is a guardrail to ensure database integrity. It occurs when primary key fields are nullable or missing the @NonNull annotation. By using non-null types, adding @NonNull, and validating composite keys, you can resolve this error quickly.

Remember: Primary keys must uniquely identify rows, and null values break this guarantee. Follow the best practices outlined here to write robust, error-free Room entities.

References#

2026-01