Metro: Fix IndexOutOfBoundsException With Module Injection

Nov 12, 2025 by Alex Johnson 59 views

Encountering an IndexOutOfBoundsException during a large project migration can be a daunting experience. This article delves into a specific scenario where this exception arises in the context of the Metro dependency injection library, particularly when dealing with parent and child classes spread across different modules.

Understanding the Issue: Member Injection Across Modules

The core problem surfaces when a parent class, residing in one module, utilizes constructor injection, and a child class in a separate module inherits from it. Add member injection to the mix, and you might find yourself facing an IndexOutOfBoundsException. Let's break down the scenario with a concrete example.

The Exception Stack Trace

The error manifests as follows:

java.lang.IndexOutOfBoundsException: Index 1 out of bounds for length 1
 at java.base/jdk.internal.util.Preconditions.outOfBounds(Preconditions.java:64)
 at java.base/jdk.internal.util.Preconditions.outOfBoundsCheckIndex(Preconditions.java:70)
 at java.base/jdk.internal.util.Preconditions.checkIndex(Preconditions.java:266)
 at java.base/java.util.Objects.checkIndex(Objects.java:361)
 at java.base/java.util.ArrayList.get(ArrayList.java:427)
 at dev.zacsweers.metro.compiler.ir.transformers.MembersInjectorTransformer.getOrGenerateInjector(MembersInjectorTransformer.kt:235)
 at dev.zacsweers.metro.compiler.ir.transformers.MembersInjectorTransformer.visitClass(MembersInjectorTransformer.kt:111)
 at dev.zacsweers.metro.compiler.ir.transformers.DependencyGraphTransformer.visitClassNew(DependencyGraphTransformer.kt:169)

This stack trace points to the MembersInjectorTransformer in Metro's compiler, specifically the getOrGenerateInjector function, as the origin of the exception. It suggests an issue with how Metro is handling member injection in the presence of inheritance across module boundaries.

Reproducing the Issue: A Minimal Example

To illustrate the problem, consider the following setup:

Module A:

open class Parent @Inject constructor() {
 @Inject
 lateinit var bar: String //this is needed
}

Module B:

class Child : Parent() {
 @Inject
 lateinit var foo: String
}

In this example, Parent is defined in Module A and has a constructor injection and a member-injected property bar. Child extends Parent in Module B and has its own member-injected property foo. The IndexOutOfBoundsException occurs during compilation when Metro attempts to generate the member injector for Child.

Root Cause Analysis

The problem seems to stem from Metro's handling of inheritance and member injection when the parent and child classes reside in different modules. Specifically, the MembersInjectorTransformer fails to correctly resolve the dependencies and generate the necessary injector when a parent class with constructor injection is involved. This is likely due to how Metro builds and traverses the dependency graph across modules.

It's important to note that the issue doesn't arise if the parent class has no member injections or if both classes are in the same module. This further supports the hypothesis that the problem is related to inter-module dependency resolution in the presence of member injection.

Impact and Mitigation

While this issue might not be widespread, it can be a significant roadblock during large-scale project migrations or in codebases that heavily rely on multi-module architectures and a mix of constructor and member injection. The original reporter mentioned that they are refactoring their code to avoid this pattern. However, a more robust solution within Metro itself would be beneficial.

Potential Solutions and Workarounds

While a comprehensive fix requires changes within Metro's compiler, there are a few potential workarounds to consider:

Refactor Code: As suggested by the original reporter, the most reliable solution is to refactor the code to avoid this specific combination of constructor and member injection across modules. This might involve moving classes to the same module or using different injection patterns.
Centralized Injection: Consider centralizing the injection logic in a common module. This can help Metro resolve dependencies more easily, but it might also increase coupling between modules.
Custom Injector: In complex cases, you could potentially implement a custom injector to handle the specific dependencies. However, this is a more advanced approach and requires a deep understanding of Metro's internals.

Diving Deeper: Metro's Internal Mechanics

To fully grasp the issue, it's helpful to understand the relevant parts of Metro's compiler. The MembersInjectorTransformer is responsible for generating the code that performs member injection. It traverses the class hierarchy and identifies fields annotated with @Inject. When it encounters a class with a parent class, it needs to ensure that the parent's dependencies are also injected. This is where the getOrGenerateInjector function comes into play. It either retrieves an existing injector for the parent class or generates a new one if it doesn't exist. The IndexOutOfBoundsException suggests that this process is failing, possibly because the parent's injector is not being correctly resolved across module boundaries.

Connection to Related Issues

The original reporter also pointed out a potential connection to a related issue (#896). That issue also deals with dependency resolution in Metro, specifically in the context of generated code. While the exact root cause might be different, both issues highlight the challenges of managing dependencies in complex scenarios.

Proposed Enhancements for Metro

Addressing this issue requires modifications within Metro's compiler. Here are some potential improvements:

Improved Dependency Resolution: Enhance the dependency resolution mechanism to correctly handle inheritance across module boundaries. This might involve modifying how Metro builds and traverses the dependency graph.
Robust Error Handling: Implement more informative error messages to help developers diagnose the issue more easily. Instead of an IndexOutOfBoundsException, a more specific error message indicating the dependency resolution failure would be much more helpful.
Automated Testing: Add automated tests to specifically cover this scenario. This would help prevent regressions in future versions of Metro.

A Proper Error Message is Key

While refactoring code can solve this, a proper error message would be helpful for developers encountering this issue. Indicating that the problem is related to cross-module inheritance and member injection would significantly speed up the debugging process. This aligns with Metro's goal of providing a smooth and developer-friendly experience.

Conclusion

The IndexOutOfBoundsException in Metro when dealing with parent and child classes in different modules, especially with constructor and member injection, highlights the complexities of dependency injection in large projects. While workarounds exist, a more robust solution within Metro's compiler is desirable. By improving dependency resolution, providing better error messages, and adding automated tests, Metro can become even more reliable and developer-friendly. Understanding the intricacies of dependency injection and Metro's internal workings is crucial for tackling such challenges effectively. By taking the time to analyze and address these issues, we can ensure that our projects are built on a solid and maintainable foundation.

For more information on dependency injection and related concepts, visit the official Dagger documentation: Dagger