AGP 7.1 ships with unshaded Dokka 1.4 and causes dependency compatibility issues

Background

Starting from 7.1, com.android.tools.build:gradle, known as Android Gradle Plugin (AGP), ships with unshaded Dokka 1.4. Initially it was introduced as a feature so that AGP users could build and publish documentation without having to apply Dokka themselves.

./gradlew buildEnvironment output for an android project:

classpath
+--- com.android.tools.build:gradle:7.1.2
|    +--- ...
|    +--- org.jetbrains.dokka:dokka-core:1.4.32
|    +--- ...
+--- ...

The problem

You might suddenly encounter this if you updated AGP from 7.0.X to 7.1.X or if you updated Dokka from any version.

Compatibility problems begin happening if AGP is applied on the root project level, and Dokka is applied for a single or a subset of modules/subprojects.

What happens then is on the root project level you have Dokka 1.4, and for the subproject you have Dokka 1.6.21 – gradle doesn’t resolve this as overriding the dependency for some reason. Because the rootproject class loader is the parent of the subproject class loader, the classes on it win. So you inevitably end up with multiple variants of the same classes from different versions of Dokka, and it all starts falling apart. The ordering in which they will be loaded is nondeterministic.

This leads to various problems:

1. You may start seeing the old, outdated UI from 1.4, it’s because HtmlRenderer and other classes are picked up from Dokka 1.4 instead of 1.6.21
2. java.lang.NoSuchMethodError errors, this is because classes loaded from 1.6.21 start referencing new methods which do not exist in classes loaded from 1.4. Which methods – completely random and depends on the classpath of your project.
3. Error while evaluating property 'unsuppressedSourceSets' – same reason as above, but for fields.
4. Unable to load class 'org.jetbrains.dokka.model.AncestryNode' - pretty much the same reason, it tries to load classes which do not exist in 1.4.
5. …

Proper solution

Since this problem is caused primarily by AGP, there’s an upstream issue for it, the fix for now is planned for 7.3: https://issuetracker.google.com/issues/229979216

Workaround / Temporary solution

The problem is caused because on the root project level you have Dokka 1.4, and you have Dokka 1.6.21 on the subproject level, and they mix.

So the workaround is to specify Dokka version in the root gradle.build.kts (optionally with apply false if you don’t want documentation generation for all modules):

// ${PROJECT_ROOT}/build.gradle.kts
plugins {
    id("org.jetbrains.dokka") version "1.6.21" apply false
}

And then apply Dokka plugin in the subproject/module that you want to generate documentation for (you can skip it if you enable dokka for all subprojects/modules):

// ${PROJECT_ROOT}/libs/mycoolidea/build.gradle.kts
plugins {
    id("org.jetbrains.dokka")
}

Then Dokka 1.4 which is shipped with AGP is overriden:

classpath
+--- com.android.tools.build:gradle:7.1.3
|    +--- ...
|    +--- org.jetbrains.dokka:dokka-core:1.4.32 -> 1.6.21
|    +--- ...
+--- ...

---

This issue will be updated once there’s anything to share.

[IgnatBeresnev]

JFYI: This issue will be resolved in AGP 7.3

[IgnatBeresnev]

Android Gradle Plugin 7.3.0 was released in September, it includes the fix for this problem: old Dokka 1.4 is not on classpath anymore, at least not at the time of using Dokka’s tasks. It has been confirmed to work.

The recommended solution is to update AGP to 7.3, but if you’re unable to do that just yet, there are some workarounds posted above for 7.1 and 7.2.

Closing the issue as resolved as there’s nothing else to be done.