toolargetool points the finger at whatever is filling the Android transaction buffer

The problem it solves is a crash with no useful stack trace

toolargetool is a tool for debugging TransactionTooLargeException on Android, and the repository description says it helps you debug those on Android 7 and later.

The failure it addresses is a specific and frustrating one. A TransactionTooLargeException is thrown when a transaction buffer is filled, and the buffer is the mechanism Android uses to pass state between components, most often through saved instance state. The stack trace that comes with the exception usually points at the framework, not at the application code that caused it, because the framework is the thing that noticed the buffer was full. The developer is left with a list of every onSaveInstanceState in the app and no way to tell which one is the culprit.

What toolargetool does is instrument the buffer and report the sizes. Its log output names the component, the size it wrote, and how that size breaks down:

D/TooLargeTool: MainActivity.onSaveInstanceState wrote: Bundle@200090398 contains 1 keys and measures 0.6 KB when serialized as a Parcel
                                                                               * android:viewHierarchyState = 0.6 KB

That line turns a guess into a measurement. The example shows a view hierarchy state of 0.6 KB, which is a number you can compare against the limit, and it names the exact callback that wrote it.

The library has earned a good word from outside. The README quotes Kedar Paranjape calling it the most underrated solution in a Stack Overflow discussion from June 2018, and the tool is on Maven Central under the com.gu.android group, which is Guardian's group id.

The scope is narrow by design. It is a diagnostic aid with one job, published as a library so that a developer can add one line, read a log, remove the dependency and ship.

Add the dependency, import one class, call one method

The integration is three steps and it is meant to be temporary.

First, include toolargetool as a dependency, and the README says in the same sentence that you can remove it again once you have debugged your crash. It is available from mavenCentral(), and you add it in your module's build.gradle:

dependencies {
    ...
    implementation 'com.gu.android:toolargetool:0.3.0'
}

Second, import the package:

import com.gu.toolargetool.TooLargeTool;

Third, add code to start logging during app start, for example in your Application.onCreate method:

TooLargeTool.startLogging(this);

The placement of that call is the part that matters. If you start logging when the crash happens, you have no data. Starting it in Application.onCreate means the log covers the entire process lifetime, so the first write that fills the buffer is recorded, along with everything that came before it.

Then you read the output. The README says to monitor logcat output to see which components are writing substantial data to the transaction buffer and when:

adb logcat -s TooLargeTool

The -s flag filters by tag, so you get only the tool's lines, which matters because the log is otherwise mixed with everything else your app is doing.

The sizing unit is KB and the measurement is of the serialised Parcel, which is the thing that actually crosses the process boundary. That is the right thing to measure, because it is the serialised form that has to fit in the buffer, not the in-memory object.

The repository is a Gradle project with a library module and a demo app

The repository layout is small and conventional. There is a toolargetool/ directory holding the library itself, an app/ directory which is the sample application, build.gradle.kts and settings.gradle.kts at the top level in the Kotlin DSL, gradle.properties, the gradle/ wrapper directory, plus gradlew and gradlew.bat at the top level, and a.github/ directory for the workflow configuration.

The primary language of the project is Kotlin, and the top level build files use the.kts variants, which is the newer Gradle Kotlin DSL style rather than the Groovy build.gradle of the era the library was first published in. The README's own examples are still shown in Groovy, which is a small inconsistency but not a problem, since the module syntax is equivalent.

The app/ module is the part that makes the library usable without a device full of your own data. A sample application that triggers the condition and logs the result is the fastest way to confirm the tool is reporting what you expect on your particular Android version, before you interpret its output on a real crash.

The licence is MIT, with the LICENSE.md file in the repository as the authoritative text, and this is a licensing statement rather than legal advice. MIT is a natural choice for a diagnostic library intended to be copied into other people's apps temporarily.

The primary language being Kotlin rather than Java also says something about the project. The library was written for modern Android, and the fact that the tool works on Android 7 and later is consistent with a codebase that targets the platform rather than the legacy support tiers it replaced.

The release process is documented because the tool has to be on Maven Central

The README carries a release process section, which is unusual for a project this small and says something about how it is used.

The note attached to it is that these instructions only work if you have the required credentials for publishing to the com.gu Sonatype repository. So the library is published under Guardian's Sonatype namespace, and the release path is the standard Gradle publishing route.

The three steps are a version bump, a commit and a tag, then a publish:

1. Increase all the version number in toolargetool/build.gradle 2. Make a commit and tag it with git tag -a v<version number> -m "<message>" 3. Run ./gradlew publishReleasePublicationToSnapshotRepository

The versioning is worth noting. The current version is 0.3.0, which is also what the dependency line in the usage instructions names, and the only tagged release is v0.3.0 from 2021-01-25. The repository is not archived and the last push was on 2026-08-02.

So the project is alive in the sense that commits are landing, but the published artefact has not moved since January 2021. For a diagnostic library that is a reasonable place to be, since the code interacts with a stable platform mechanism and a new release is only needed if the framework's internals change. The cost is that a developer on a recent Android version is using a five-year-old build, and if the tool needs adapting to a framework change, that adaptation has to be made locally rather than pulled from Maven Central.

The README also carries an unedited note that the example logcat output could be improved, marked with a TODO. That kind of small rough edge in the documentation is a useful signal about the project's pace.

What the tool does not do, and the alternative of reading the buffer yourself

It is worth being clear about the limits, because the name suggests more than it delivers.

toolargetool measures. It does not prevent the exception, it does not truncate the offending bundle, and it does not fix the problem. Its output is a diagnosis, and the fix is still yours: find the view hierarchy you are saving, and stop saving it, or save a smaller version of it. The README's framing is consistent with that, since the tool is presented as something you add, read, and then remove.

There is also a scope limit in what it reports. It reports what was written to the transaction buffer and how large it was when serialised as a Parcel. It does not report what happens after that, and it does not model the per-process buffer limits or the binder transaction accounting that produces the exception in the first place. For a developer whose problem is a single oversized bundle, that is exactly the information needed. For a developer whose problem is that many small writes across many components add up, the per-write numbers are still the right signal, since the log shows when each write happened.

The alternative, if you would rather not add a dependency, is to write the measurement yourself. The framework gives you the same information, since you can serialise the bundle you are about to save and measure it, but you would be doing that in every onSaveInstanceState you suspect, one at a time, rather than getting a report across the whole process. The library's value is not that the measurement is hard, it is that it is applied everywhere at once.

The other alternative is to reason about it from the crash report and the saved instance state bundle in the crash log, which tells you how large the total was but not which component contributed which part. That is the difference the tool's log line makes.

Editorial conclusion

Adopt toolargetool if you are chasing a TransactionTooLargeException and the stack trace has not told you which callback is responsible, and if you can ship a build with the dependency included and read the output from logcat. Do not adopt it as a permanent dependency, because the README says explicitly that you can remove it again once you have debugged the crash, and it measures rather than prevents. Before you add it, plan to add TooLargeTool.startLogging(this) in Application.onCreate so the log covers the whole process lifetime, and note that the only tagged release is v0.3.0 from 2021-01-25.

Frequently asked questions

Official sources

1. guardian/toolargetool on GitHub
2. Issues
3. License: MIT
4. README
5. Releases