WSL2_INTEGRATION_FAILURE

WSL2_INTEGRATION_FAILURE to błąd wskazujący na niepowodzenie integracji podsystemu WSL2 z komponentami hosta Windows.

Co oznacza WSL2_INTEGRATION_FAILURE

WSL2_INTEGRATION_FAILURE oznacza niepowodzenie połączenia podsystemu Windows Subsystem for Linux 2 z elementami systemu Windows, które są potrzebne do uruchomienia dystrybucji Linuksa. Nie jest to nazwa jednego, uniwersalnego kodu błędu definiowanego przez wszystkie wersje WSL2. Taki zapis może pochodzić z dziennika aplikacji, narzędzia diagnostycznego albo programu korzystającego z integracji z WSL2. Wspólnym elementem jest sytuacja, w której aplikacja nie może prawidłowo skomunikować się z uruchomionym środowiskiem WSL2.

WSL2 korzysta z własnego jądra Linuksa oraz wirtualnego dysku dystrybucji, zwykle przechowywanego w pliku VHDX. Do działania potrzebuje między innymi składników WSL, platformy maszyny wirtualnej, usług systemowych, poprawnie zarejestrowanej dystrybucji i sprawnej konfiguracji sieciowej. Awaria dowolnego z tych elementów może zostać przedstawiona jako błąd integracji, nawet gdy bezpośrednia przyczyna znajduje się w aktualizacji systemu, konfiguracji dystrybucji, uszkodzonym pliku dysku albo niedostępnym komponencie Windows.

Warstwy WSL2, które mogą przerwać współpracę

Podczas uruchamiania polecenia wsl system najpierw rozpoznaje zainstalowaną dystrybucję i jej wersję, a następnie przekazuje żądanie do infrastruktury WSL2. Dystrybucja działa w odrębnym środowisku z jądrem Linuksa, natomiast użytkownik może korzystać z plików Windows, procesów Windows i przekierowania wejścia oraz wyjścia. Integracja nie oznacza więc, że program linuksowy staje się natywnym procesem Windows. Oznacza współdziałanie kilku warstw, między którymi muszą działać mechanizmy komunikacyjne i montowanie systemów plików.

Istotne znaczenie ma również stan dystrybucji. Polecenie wsl -l -v pokazuje zarejestrowane dystrybucje oraz informację, czy dana dystrybucja używa WSL1 czy WSL2. Polecenie wsl --status pozwala sprawdzić ogólny stan środowiska WSL, a wsl --version jest przydatne w instalacjach, w których WSL jest dostarczany jako aktualizowany składnik systemu. Jeżeli dystrybucja nie jest zarejestrowana, pozostaje w stanie błędu albo jej wirtualny dysk nie może zostać otwarty, aplikacja integrująca się z WSL2 może zgłosić WSL2_INTEGRATION_FAILURE bez podania bardziej szczegółowej przyczyny.

Rozdzielenie problemu konfiguracji od awarii danych

Diagnostykę warto rozpocząć od ustalenia, czy problem dotyczy całego WSL2, czy tylko jednej dystrybucji albo konkretnego programu. Jeżeli wsl -l -v nie działa, nie pokazuje dystrybucji lub zwraca błąd przed jej uruchomieniem, podejrzenie pada na składniki WSL2 i konfigurację systemu. Jeżeli polecenie działa, lecz jedna dystrybucja nie startuje, należy sprawdzić jej stan, dostępność pliku VHDX oraz ostatnie zmiany systemowe. Osobny przypadek występuje wtedy, gdy dystrybucja uruchamia się poprawnie z terminala, ale nie jest widoczna dla zewnętrznej aplikacji. Wtedy problem może dotyczyć sposobu, w jaki ta aplikacja wykrywa lub wywołuje WSL2.

Bezpiecznym testem podstawowym jest wykonanie wsl --shutdown, które zatrzymuje działające instancje WSL2, a następnie ponowne uruchomienie dystrybucji. Do sprawdzenia aktualizacji służy wsl --update. Nie należy jednak usuwać dystrybucji poleceniem wsl --unregister bez potwierdzonej kopii potrzebnych danych, ponieważ wyrejestrowanie usuwa jej środowisko wraz z zawartością przechowywaną w wirtualnym dysku. Jeżeli problem pojawił się po zmianie konfiguracji, należy porównać stan funkcji opcjonalnych Windows, ustawienia platformy maszyny wirtualnej, wersję WSL oraz komunikaty w Podglądzie zdarzeń. Samo ponowne instalowanie dystrybucji bez ustalenia przyczyny może utrudnić ocenę, czy uszkodzona była konfiguracja, czy dane środowiska.

Postępowanie przy błędzie na komputerze z Windows

Praktyczna kolejność sprawdzania obejmuje identyfikację wersji systemu Windows i WSL, listę dystrybucji, ich stan oraz próbę uruchomienia WSL2 bez pośrednictwa dodatkowej aplikacji. Następnie można sprawdzić, czy działa aktualizacja składnika WSL, czy system nie oczekuje na ponowne uruchomienie oraz czy funkcje „Windows Subsystem for Linux” i „Virtual Machine Platform” są dostępne i włączone. W przypadku komunikatów związanych z siecią trzeba odróżnić błąd samego WSL2 od problemu zapory, klienta VPN, oprogramowania filtrującego ruch albo nieprawidłowego interfejsu wirtualnego. Każdy z tych przypadków może ograniczyć integrację, ale wymaga innego postępowania.

Warszawskie Pogotowie Komputerowe zajmuje się profesjonalną naprawą laptopów i komputerów PC, w tym diagnostyką problemów z oprogramowaniem systemowym oraz konfiguracją środowiska Windows. Przy błędzie WSL2_INTEGRATION_FAILURE istotne jest zachowanie komunikatów, wyników poleceń wsl -l -v i wsl --status, informacji o ostatnich aktualizacjach oraz danych o tym, czy błąd występuje w terminalu, czy wyłącznie w określonej aplikacji. Takie rozdzielenie objawów pozwala ustalić, czy naprawy wymaga składnik Windows, rejestracja dystrybucji, plik środowiska WSL2, konfiguracja sieciowa czy integracja po stronie programu korzystającego z WSL2.