.NET Conf

Błąd „A fatal error occurred. The folder [/usr/share/dotnet/host/fxr] does not exist” to jedno z najczęstszych i najpoważniejszych wyzwań dla deweloperów .NET na Linuksie. Ten krytyczny problem uniemożliwia uruchomienie środowiska runtime .NET, blokując pracę programistyczną i wdrożenia produkcyjne. Gdy .NET Common Language Runtime (CLR) nie znajduje kluczowych komponentów hostujących, proces uruchamiania aplikacji zostaje całkowicie przerwany, ponieważ wymagane katalogi zostały naruszone, przeniesione lub nie zostały utworzone podczas instalacji.

Spis treści [odkryj]

Zrozumienie technicznych podstaw błędu

Kluczową rolę pełni katalog /usr/share/dotnet/host/fxr jako repozytorium bibliotek Framework Resolver (FXR), umożliwiających aplikacjom wybór i ładowanie odpowiednich wersji środowiska .NET. Podczas uruchamiania aplikacji .NET, komponent hostujący przeszukuje konkretne ścieżki instalacyjne — od systemowych po lokalne — aby odnaleźć wymagane biblioteki. Brak lub uszkodzenie katalogu FXR skutkuje natychmiastowym przerwaniem uruchamiania aplikacji i brakiem dostępu do większości narzędzi diagnostycznych, co znacząco utrudnia rozpoznanie źródła problemu.

Struktura katalogów .NET na Linuksie opiera się na hierarchii:

  • /usr/share/dotnet zawiera kluczowe podkatalogi,
  • host/fxr skupia katalogi wersji FXR,
  • każda wersja FXR przechowuje plik libhostfxr.so, niezbędny do hostowania runtime,
  • brak lub uszkodzenie powyższych struktur blokuje łańcuch uruchamiania .NET.

Zrozumienie tej architektury pozwala wdrożyć skuteczne techniki naprawcze, które eliminują rzeczywiste źródła problemu.

Konflikty zarządzania pakietami i problemy z repozytoriami

Błąd katalogu FXR na Linuksie najczęściej powodują konflikty związane ze sposobem instalacji komponentów .NET. Dotyczy to szczególnie środowisk, gdzie korzysta się z różnych repozytoriów i systemów zarządzania pakietami. Oto typowe scenariusze prowadzące do problemów:

  • instalacja .NET z różnych źródeł (np. repozytoria dystrybucji i Microsoft),
  • niezgodności ścieżek instalacji — Ubuntu stosuje /usr/lib/dotnet, Microsoft: /usr/share/dotnet,
  • systemowe aktualizacje podmieniające pakiety na wersje z nieoczekiwanych repozytoriów,
  • instalacja wielu wersji .NET bez prawidłowej obsługi zależności,
  • nietypowe lub mieszane skrypty konfiguracyjne wpływające na układ katalogów.

Różnice w ścieżkach instalacyjnych oraz brak spójności podczas instalacji lub aktualizacji doprowadzają do sytuacji, w której aplikacja .NET nie odnajduje wymaganych katalogów host/fxr.

Konfiguracja zmiennych środowiskowych i wykrywanie runtime

Bardzo ważną rolę w procesie wykrywania środowiska uruchomieniowego .NET pełnią zmienne środowiskowe. Szczególną uwagę należy zwrócić na:

  • DOTNET_ROOT – wyznacza ścieżkę do instalacji runtime. Niewskazanie tej zmiennej lub podanie błędnej wartości skutkuje błędem katalogu;
  • DOTNET_HOST_PATH, DOTNET_ROOT_X64 – pozwalają kierować proces wykrywania komponentów w środowiskach niestandardowych lub kontenerowych;
  • pliki konfiguracyjne, np. /etc/dotnet/install_location – umożliwiają rejestrację niestandardowych ścieżek instalacji .NET na poziomie systemu;
  • brak lub niewłaściwe ustawienie powyższych elementów często generuje krytyczne błędy odczytu katalogu.

Prawidłowa konfiguracja zmiennych środowiskowych pozwala skutecznie rozwiązać problem błędu katalogu host/fxr bez konieczności ingerencji w pozostałe aspekty systemu.

Kompleksowe procedury naprawy

Rozwiązanie krytycznego błędu katalogu FXR wymaga uporządkowanych, przemyślanych kroków. Najefektywniejsza procedura naprawcza powinna obejmować następujące etapy:

  • deinstalacja wszystkich instalacji .NET – zarówno z repozytoriów systemowych, jak i Microsoft, włączając powiązane pakiety (SDK, runtime, ASP.NET Core, .NET Standard);
  • usunięcie plików konfiguracyjnych i preferencji repozytoriów – np. /etc/apt/sources.list.d/microsoft-prod.list w przypadku korzystania z repozytoriów dystrybucyjnych;
  • ponowna instalacja .NET – wyłącznie z jednego, wybranego źródła, najlepiej po określeniu preferencji APT (np. /etc/apt/preferences.d/99microsoft-dotnet.pref);
  • odpowiednia konfiguracja zmiennych środowiskowych – poprawne ustawienie DOTNET_ROOT i aktualizacja PATH dla wskazania właściwego katalogu binariów.

Te działania pozwalają przywrócić spójność środowiska oraz uniknąć ponownych konfliktów w przyszłości.

Zaawansowana konfiguracja i zarządzanie uprawnieniami

Likwidacja błędu katalogu FXR wymaga niekiedy również korekty uprawnień do systemu plików. Warto zwrócić uwagę na:

  • sprawdzanie dostępu odczytu do całego drzewa .NET,
  • kontrolę właściciela oraz praw dostępu do katalogu host/fxr i jego plików,
  • korzystanie z dedykowanych grup użytkowników lub list kontroli dostępu (ACL) zamiast szerokiego otwierania uprawnień,
  • implementację modelu, w którym runtime znajduje się w katalogu dostępnym dla użytkowników aplikacji.

W środowiskach self-contained runtime przechowywany jest wewnątrz katalogu aplikacji, natomiast warianty framework-dependent wymagają prawidłowych uprawnień na poziomie całego systemu.

Narzędzia diagnostyczne i techniki rozwiązywania problemów

Zaawansowana diagnostyka błędu katalogu FXR możliwa jest dzięki wbudowanym narzędziom .NET. Warto wykorzystywać:

  • zmienną COREHOST_TRACE=1 dla szczegółowego logowania procesu szukania komponentów,
  • polecenie dotnet --info do przeglądu zainstalowanych SDK oraz ścieżek runtime,
  • analizę logów systemowych i aplikacyjnych pod kątem błędów uprawnień lub zarządzania pakietami.

COREHOST_TRACE pozwala wykryć, które ścieżki są sprawdzane i dlaczego nie dochodzi do prawidłowego odnalezienia katalogów, natomiast dotnet --info szybko ujawnia rozbieżności w konfiguracji środowiska.

Strategie zapobiegania i najlepsze praktyki

Aby ograniczyć ryzyko powrotu błędu katalogu /usr/share/dotnet/host/fxr, rekomendowane są poniższe działania prewencyjne:

  • standardyzacja źródła pakietów (.NET wyłącznie z jednego repozytorium),
  • konfiguracja preferencji APT przez pliki w katalogu /etc/apt/preferences.d/,
  • regularna weryfikacja integralności instalacji przy użyciu dotnet --info,
  • wdrożenie własnych skryptów monitorujących obecność i dostępność katalogu host/fxr,
  • spisanie i aktualizacja dokumentacji oraz procedur instalacyjnych dla całego zespołu.

Konsekwencja we wdrażaniu tych praktyk przeciwdziała nagłym awariom oraz znacznie skraca czas ewentualnych napraw.

Uwarunkowania kontenerowe i wirtualizacyjne

Błąd katalogu FXR nabiera nowego znaczenia w środowiskach kontenerowych, gdzie hierarchia plików może być odmienna, a obrazy bazowe korzystają z różnych źródeł .NET. W takich przypadkach należy zadbać o:

  • precyzyjne deklarowanie RuntimeIdentifier i ścieżek instalacyjnych w plikach projektu,
  • wyraźne ustawianie zmiennych środowiskowych na etapie budowania obrazu,
  • uruchamianie narzędzi diagnostycznych (dotnet --info, COREHOST_TRACE) w konteście kontenera,
  • dobór obrazów bazowych zgodnych z oczekiwaniami aplikacji oraz procesu wdrożeniowego.

Prawidłowa diagnostyka wymaga testowania środowiska uruchomieniowego bezpośrednio wewnątrz kontenera.

Warianty i specyfika poszczególnych dystrybucji

Poszczególne dystrybucje Linuksa mają różne mechanizmy zarządzania pakietami .NET oraz własne konwencje dotyczące ścieżek instalacyjnych i polityk aktualizacji:

  • Ubuntu umożliwia instalację zarówno z natywnych repozytoriów, jak i oficjalnych źródeł Microsoft,
  • Fedora i Red Hat stosują odmienną strukturę domyślną katalogów oraz autorskie mechanizmy systemowe do zarządzania alternatywami,
  • niektóre dystrybucje przepakowują oficjalny .NET, dodając własne poprawki i zmieniając ścieżki katalogowe,
  • różne są zasady numerowania wersji, harmonogramy aktualizacji i formaty plików konfiguracyjnych.

Zawsze należy dostosować technikę naprawy do specyfiki wybranej dystrybucji, unikając uniwersalnych procedur naprawczych.

Długoterminowe utrzymanie i monitoring

Długotrwała stabilność środowiska .NET wymaga systematycznego monitorowania i wdrażania dobrych praktyk obsługi:

  • regularna weryfikacja spójności katalogów i zmiennych środowiskowych,
  • automatyzacja testów oraz skryptów monitorujących stan kluczowych plików .NET,
  • dokumentowanie wszystkich czynności naprawczych i konfiguracyjnych,
  • bieżąca aktualizacja preferencji repozytoriów i skryptów monitorujących.

Takie podejście gwarantuje ograniczenie powrotów błędów i zapewnia stabilność środowiska .NET przez długi czas.