Tencent/matrix · error · IllegalStateException

token with name=$name not found

Error message

token with name=$name not found

What it means

The name-based overload removeToken(name) removes the ProcessToken registered for a process name. It throws IllegalStateException("token with name=$name not found") when no such name is present in nameToToken — the process was never registered, or its token was already removed via the pid path.

Solutions

1. Guard with a map lookup (or catch IllegalStateException) so removing an unknown name is a no-op.
2. Keep pid/name removal symmetric: removing by one key should not leave the other path expecting an entry.
3. Only call removeToken for names obtained from the supervisor's live token registry.
4. Log-and-skip unknown names in cleanup loops instead of letting the exception propagate.

Example fix

// before
val token = removeToken(name)
// after
val token = try {
    removeToken(name)
} catch (e: IllegalStateException) {
    MatrixLog.w(TAG, "token already removed for name=$name")
    null
}

if (name in supervisor.registeredNames) removeToken(name)

val token = try {
    removeToken(name)
} catch (e: IllegalStateException) {
    null // unknown or already-removed name — treat as no-op
}

When it happens

Trigger: Calling removeToken(name) for a subordinate name that never registered, was already removed by removeToken(pid), or whose entry was purged on binder death before this call.

Common situations: Config-driven white/blacklist cleanup invoking removeToken for processes that never connected; double cleanup between pid-based and name-based paths; renamed processes after a build configuration change.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• token with pid=$pid not found
• call forbidden
• NOT allow for subordinate processes
• Supervisor NOT initialized yet or Supervisor is disabled!!!
• backgroundLruKill should only be called in supervisor

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

Appendix: source

Thrown at matrix/matrix-android/matrix-android-lib/src/main/java/com/tencent/matrix/lifecycle/supervisor/SupervisorService.kt:338

        fun removeToken(pid: Int): ProcessToken {
            val rm = pidToToken.remove(pid)
            rm?.let {
                nameToToken.remove(rm.name)
                return rm
            }
            throw IllegalStateException("token with pid=$pid not found")
        }

        fun isEmpty(): Boolean =
            pidToToken.isEmpty() || pidToToken.all { it.key == Process.myPid() }

        fun removeToken(name: String): ProcessToken {
            val rm = nameToToken.remove(name)
            rm?.let {
                pidToToken.remove(rm.pid)
                return rm
            }
            throw IllegalStateException("token with name=$name not found")
        }
    }

    private class RemoteProcessLifecycleProxy(val token: ProcessToken) : StatefulOwner() {

        init {
            DispatcherStateOwner.addSourceOwner(
                token.statefulName,
                this
            )
        }

        companion object {

            private val processProxies by lazy { ConcurrentHashMap<ProcessToken, ConcurrentHashMap<String, RemoteProcessLifecycleProxy>>() }

            fun getProxy(token: ProcessToken) =
                processProxies.getOrPut(token, { ConcurrentHashMap() })

View on GitHub (pinned to 3b8293bd65)