microg/GmsCore · error · IllegalArgumentException

Unknown key: $key

Error message

Unknown key: $key

What it means

SettingsProvider.queryGcm resolves GCM settings keys in a `when` expression and throws IllegalArgumentException for any key outside the known set (e.g. Gcm.NETWORK_MOBILE/NETWORK_WIFI/NETWORK_OTHER/LEARNT_*). It is thrown when query() receives a projection column that is not a recognized GCM setting.

Source

Thrown at play-services-base/core/src/main/kotlin/org/microg/gms/settings/SettingsProvider.kt:178

    private fun queryGcm(p: Array<out String>): Cursor = MatrixCursor(p).addRow(p) { key ->
        when (key) {
            Gcm.ENABLE_GCM -> getSettingsBoolean(key, false)
            Gcm.FULL_LOG -> getSettingsBoolean(key, true)
            Gcm.CONFIRM_NEW_APPS -> getSettingsBoolean(key, false)

            Gcm.LAST_PERSISTENT_ID -> preferences.getString(key, "") ?: ""

            Gcm.NETWORK_MOBILE -> Integer.parseInt(preferences.getString(key, "0") ?: "0")
            Gcm.NETWORK_WIFI -> Integer.parseInt(preferences.getString(key, "0") ?: "0")
            Gcm.NETWORK_ROAMING -> Integer.parseInt(preferences.getString(key, "0") ?: "0")
            Gcm.NETWORK_OTHER -> Integer.parseInt(preferences.getString(key, "0") ?: "0")

            Gcm.LEARNT_MOBILE -> preferences.getInt(key, 300000)
            Gcm.LEARNT_WIFI -> preferences.getInt(key, 300000)
            Gcm.LEARNT_OTHER -> preferences.getInt(key, 300000)

            else -> throw IllegalArgumentException("Unknown key: $key")
        }
    }

    private fun updateGcm(values: ContentValues) {
        if (values.size() == 0) return
        val editor = preferences.edit()
        values.valueSet().forEach { (key, value) ->
            when (key) {
                Gcm.ENABLE_GCM -> editor.putBoolean(key, value as Boolean)
                Gcm.FULL_LOG -> editor.putBoolean(key, value as Boolean)
                Gcm.CONFIRM_NEW_APPS -> editor.putBoolean(key, value as Boolean)

                Gcm.LAST_PERSISTENT_ID -> editor.putString(key, value as String?)

                Gcm.NETWORK_MOBILE -> editor.putString(key, (value as Int).toString())
                Gcm.NETWORK_WIFI -> editor.putString(key, (value as Int).toString())
                Gcm.NETWORK_ROAMING -> editor.putString(key, (value as Int).toString())
                Gcm.NETWORK_OTHER -> editor.putString(key, (value as Int).toString())

View on GitHub (pinned to 157c9d86ac)

Solutions

1. Use only keys defined in org.microg.gms.settings.Gcm (check the constants in your microG version)
2. Add a version check or try-catch around provider queries when keys may differ between versions
3. If adding new settings, extend queryGcm's `when` to cover them

Example fix

// before
cursor = resolver.query(GCM_URI, arrayOf("gcm.learnMobile"), null, null, null) // typo
// after
cursor = resolver.query(GCM_URI, arrayOf(Gcm.LEARNT_MOBILE), null, null, null)

val known = setOf(Gcm.NETWORK_MOBILE, Gcm.NETWORK_WIFI, Gcm.NETWORK_OTHER, Gcm.LEARNT_MOBILE, Gcm.LEARNT_WIFI, Gcm.LEARNT_OTHER)
require(keys.all { it in known }) { "Unknown GCM keys: ${keys - known}" }

try {
    cursor = resolver.query(GCM_URI, keys, null, null, null)
} catch (e: IllegalArgumentException) {
    Log.w(TAG, "Unsupported GCM key for this microG version", e)
    cursor = null
}

When it happens

Trigger: query(contentUri=gcmSettings, projection=[unknownKey]) — the requested key does not match any constant in the Gcm settings object (typo, key removed/renamed in a newer/older version, or querying an auth/exposure/etc. key through the GCM branch).

Common situations: Caller builds the projection string dynamically or hardcodes a key name from an old microG version; passing keys belonging to other settings groups (Auth.*, DroidGuard.*) to the gcm URI.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• deleteAll was set to true but keys were also provided
• Element in keys cannot be null or empty
• retrieveAll was set to true but other constraint(s) was also
• Element in keys cannot be null or empty
• Access denied, missing google package permission or GET_ACCO

AI-assisted analysis of microg/GmsCore@157c9d86ac (2026-09-06). Data as JSON: /api/errors/a3e8357a07b12db5. Report an issue: GitHub.