Tencent/matrix · error · IllegalArgumentException

max check times should be greater than 0

Error message

max check times should be greater than 0

What it means

ProcessStagedBackgroundOwner.maxCheckTimes limits how many interval checks run before declaring the process backgrounded. It must be at least 1; setting a value <= 0 throws IllegalArgumentException because a zero/negative count makes the staged check never complete.

Solutions

1. Set maxCheckTimes to at least 1.
2. Guard computed values: coerceAtLeast(1) before assigning.
3. If you want to disable staged checking, don't use ProcessStagedBackgroundOwner; use ProcessExplicitBackgroundOwner instead.

Example fix

// before
ProcessStagedBackgroundOwner.maxCheckTimes = 0 // throws
// after
ProcessStagedBackgroundOwner.maxCheckTimes = computedTimes.coerceAtLeast(1)

fun setStagedTimes(times: Int) {
    require(times > 0) { "maxCheckTimes must be > 0" }
    ProcessStagedBackgroundOwner.maxCheckTimes = times
}

null

try {
    ProcessStagedBackgroundOwner.maxCheckTimes = configuredTimes
} catch (e: IllegalArgumentException) {
    MatrixLog.w(TAG, "times must be > 0, using default")
}

When it happens

Trigger: Assigning ProcessStagedBackgroundOwner.maxCheckTimes = 0 or a negative number while configuring the staged background detection.

Common situations: Disabling staged checks by setting 0 (not supported); computing the count dynamically (e.g. totalWindow / interval) and producing 0 when the interval is large.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• interval should NOT be less than 10s
• ---APK-UNZIP-PATH can not be null!
• ---APK-UNZIP-PATH can not be null!
• ---APK-UNZIP-PATH can not be null!
• TAG + "---The path of tool 'nm' is not given!"

AI-assisted analysis of Tencent/matrix@3b8293bd65 (2026-09-08). Data as JSON: /api/errors/a4cb04cea22091a1. Report an issue: GitHub.

Appendix: source

Thrown at matrix/matrix-android/matrix-android-lib/src/main/java/com/tencent/matrix/lifecycle/owners/ProcessBackgroundStateOwner.kt:149

 *
 * notice: same as [ProcessExplicitBackgroundOwner]
 */
object ProcessStagedBackgroundOwner : StatefulOwner(), IBackgroundStatefulOwner {
    private const val TAG = "Matrix.background.Staged"

    var maxCheckInterval = MAX_CHECK_INTERVAL
        set(value) {
            if (value < TimeUnit.SECONDS.toMillis(10)) {
                throw IllegalArgumentException("interval should NOT be less than 10s")
            }
            field = value
            MatrixLog.i(TAG, "set max check interval as $value")
        }

    var maxCheckTimes = MAX_CHECK_TIMES
        set(value) {
            if (value <= 0) {
                throw IllegalArgumentException("max check times should be greater than 0")
            }
            field = value
            MatrixLog.i(TAG, "set max check interval as $value")
        }

    private val checkTask = object : TimerChecker(TAG, maxCheckInterval, maxCheckTimes) {
        override fun action(): Boolean {
            if (ProcessExplicitBackgroundOwner.active()
                && (ProcessUILifecycleOwner.hasRunningAppTask()
                    .also { MatrixLog.i(TAG, "hasRunningAppTask? $it") }
                        || ProcessUICreatedStateOwner.active())
            ) {
                MatrixLog.i(TAG, "turn ON")
                turnOn() // staged background
                return true
            }
            MatrixLog.i(TAG, "turn off")
            turnOff() // means deep background

View on GitHub (pinned to 3b8293bd65)