What causes "interval should NOT be less than 10s" in Tencent/matrix?

Set maxCheckInterval to at least 10_000L milliseconds (10s).

Tencent/matrix · error · IllegalArgumentException

interval should NOT be less than 10s

Error message

interval should NOT be less than 10s

What it means

ProcessExplicitBackgroundOwner detects background state with a periodic timer whose interval is maxCheckInterval. Intervals below 10 seconds would make the check too aggressive (waking the process constantly), so the setter throws IllegalArgumentException if the value is less than 10_000 ms.

Solutions

Set maxCheckInterval to at least 10_000L milliseconds (10s).
Convert seconds to milliseconds: TimeUnit.SECONDS.toMillis(seconds).
Keep the default MAX_CHECK_INTERVAL unless you need a longer interval.

Example fix

// before
ProcessExplicitBackgroundOwner.maxCheckInterval = 5_000L // throws
// after
ProcessExplicitBackgroundOwner.maxCheckInterval = 10_000L // 10s minimum

Defensive patterns

Strategy: validation

Validate before calling

fun setExplicitInterval(ms: Long) {
    require(ms >= TimeUnit.SECONDS.toMillis(10)) { "interval must be >= 10s" }
    ProcessExplicitBackgroundOwner.maxCheckInterval = ms
}

Type guard

null

Try / catch

try {
    ProcessExplicitBackgroundOwner.maxCheckInterval = configuredMs
} catch (e: IllegalArgumentException) {
    MatrixLog.w(TAG, "interval too small, using default")
}

Prevention

Store the config value in seconds and convert with TimeUnit.SECONDS.toMillis.
Clamp user/config values to >= 10_000L before assigning.
Keep the default MAX_CHECK_INTERVAL unless validated otherwise.

When it happens

Trigger: Assigning ProcessExplicitBackgroundOwner.maxCheckInterval = < 10000 (milliseconds), e.g. a config value in seconds written as milliseconds or a tuning attempt like 5000L.

Common situations: Confusing seconds and milliseconds in remote config; trying to make background detection more responsive by shrinking the interval below the supported floor.

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

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

Appendix: source

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

 * NOTICE:
 *
 * [ForegroundServiceLifecycleOwner] is an optional StatefulOwner which is disabled by default and
 * can be enabled by [MatrixLifecycleConfig.enableFgServiceMonitor]
 * [OverlayWindowLifecycleOwner] is similar, which can be enabled by [MatrixLifecycleConfig.enableOverlayWindowMonitor]
 *
 * If the [ForegroundServiceLifecycleOwner] were disabled, this owner would start the timer checker
 * to check the ForegroundService states. If there were foreground Service launched after UI turned
 * background, the callback [IStateObserver.off] or [IMatrixLifecycleCallback.onForeground]
 * wouldn't be call until we call the [active] or the state of upstream Owner changes.
 * So do [OverlayWindowLifecycleOwner].
 */
object ProcessExplicitBackgroundOwner : StatefulOwner(), IBackgroundStatefulOwner {
    private const val TAG = "Matrix.background.Explicit"

    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")
        }

    private val checkTask = object : TimerChecker(TAG, maxCheckInterval) {
        override fun action(): Boolean {
            val uiForeground by lazy { ProcessUIStartedStateOwner.active() }
            val fgService by lazy { ForegroundServiceLifecycleOwner.hasForegroundService() }
            val visibleWindow by lazy { OverlayWindowLifecycleOwner.hasOverlayWindow() }

            if (uiForeground) {
                MatrixLog.i(TAG, "turn OFF for UI foreground")
                turnOff() // must be NOT in explicit background and do NOT need polling checker
                return false
            }

            if (!fgService && !visibleWindow) {

View on GitHub (pinned to 3b8293bd65)