Only the original thread that created a view hierarchy can touch its views

Приложение падает при попытке что-нибудь показать на экране, а в логе:

android.view.ViewRootImpl$CalledFromWrongThreadException:
Only the original thread that created a view hierarchy can touch its views.

Сообщение описывает правило буквально: интерфейс трогает только тот поток, который его создал, — главный. Любой другой получает исключение. Вопрос всегда один: как мы из него вышли и не заметили.

Как это происходит с корутинами

Самый частый случай — корутина запущена не на том диспетчере:

viewModelScope.launch(Dispatchers.IO) {   // вся корутина в фоне
    val data = repository.load()
    textView.text = data.title            // падение
}

Диспетчер указан у самого билдера, а значит всё тело корутины выполняется в фоновом потоке, включая последнюю строчку. Правильно наоборот: корутина живёт на главном потоке, а в фон уходит только то, что должно:

viewModelScope.launch {                       // Main
    val data = withContext(Dispatchers.IO) {
        repository.load()
    }
    textView.text = data.title                // снова Main
}

Второй случай — колбэк чужой библиотеки. Retrofit старого образца, слушатель сокета, обработчик из SDK: они вызывают вас на своём потоке, и всё, что оттуда уходит в интерфейс, падает. Возвращаться нужно явно, через withContext(Dispatchers.Main).

Третий — Thread или Executor, доставшиеся от старого кода. С корутинами они не дружат, и про главный поток не знают.

Чего делать не надо

Вокруг этой ошибки накопился набор решений, которые её прячут вместо того, чтобы чинить.

  • runOnUiThread { } и view.post { } — работают, но возвращают нас к коду на колбэках, от которого корутины и избавляют;
  • обернуть всё подряд в withContext(Dispatchers.Main) — интерфейс перестанет падать, но тяжёлая работа переедет в главный поток, и вместо падения вы получите подвисания;
  • ловить исключение в try/catch — обновление просто молча не произойдёт.

Правило, после которого ошибка не возвращается

Диспетчер выбирает не тот, кто вызывает, а сама функция. Репозиторий сам уводит работу в Dispatchers.IO и возвращает готовый результат. Тогда во ViewModel и на экране вы всегда на главном потоке и можете про диспетчеры не думать:

class UserRepository(private val api: Api) {
    suspend fun load(): User = withContext(Dispatchers.IO) {
        api.getUser()
    }
}

При таком устройстве указывать диспетчер у launch почти никогда не нужно — а именно это указание и порождает ошибку чаще всего.

В Compose её почти не бывает

Compose обновляет интерфейс через состояние, а не прямым обращением к вьюхам, поэтому напороться сложнее. Но соседняя проблема остаётся: если собирать поток без учёта жизненного цикла или запускать корутину прямо в теле composable-функции, вы получите другие сюрпризы — для этого есть collectAsStateWithLifecycle() и LaunchedEffect.

Родственные исключения с той же причиной: NetworkOnMainThreadException — сеть в главном потоке, и жалоба Room на обращение к базе из главного потока. Это та же ошибка, только зеркальная: не интерфейс из фона, а фоновая работа в интерфейсе.

Про диспетчеры и withContext — в руководстве по корутинам.