.NET Conf

Błąd „A fatal error occurred. The folder [/usr/share/dotnet/host/fxr] does not exist” jest jednym z najczęstszych problemów, z jakimi mierzą się deweloperzy .NET na systemach Linux. Komunikat ten wskazuje na brak kluczowego folderu, bez którego środowisko uruchomieniowe .NET nie może funkcjonować, uniemożliwiając uruchamianie aplikacji opartych na tej technologii. Główne źródła problemu to: niepełna instalacja, konflikty między repozytoriami oraz różne lokalizacje pakietów zależnie od dystrybucji. Zalecane jest przeprowadzenie systematycznej diagnostyki, usunięcie wszystkich konfliktowych pakietów i reinstalacja .NET z jednego, sprawdzonego źródła. Szczególną uwagę należy zwrócić na różnice między pakietami Microsoft a tymi pochodzącymi z repozytoriów dystrybucji Linux, które mogą prowadzić do poważnych problemów z kompatybilnością oraz stabilnością.

Spis treści [odkryj]

Charakterystyka i mechanizm błędu

Folder host/fxr (Framework X Resolver) w strukturze .NET jest odpowiedzialny za inicjalizację środowiska uruchomieniowego oraz rozwiązywanie zależności frameworków. Jego brak powoduje natychmiastowe przerwanie procesu startu aplikacji. Apphost .NET szuka biblioteki libhostfxr.so właśnie w /usr/share/dotnet/host/fxr, a każda niezgodność w strukturze folderów uniemożliwia poprawne uruchomienie aplikacji.

Domyślna ścieżka instalacji oraz oczekiwanych plików zależy od metody instalacji i dystrybucji Linux. Przykładowo: instalacja .NET z repozytorium Microsoft umieszcza folder w /usr/share/dotnet, a z natywnego repozytorium Ubuntu – w /usr/lib/dotnet. Te pozornie niewielkie różnice odpowiadają za większość przypadków błędu.

Struktura katalogu fxr zawiera podfoldery specyficzne dla każdej wersji środowiska, na przykład /usr/share/dotnet/host/fxr/6.0.0 lub /usr/share/dotnet/host/fxr/8.0.4, gdzie znajduje się kluczowa biblioteka libhostfxr.so.

Główne przyczyny wystąpienia problemu

Do najczęstszych źródeł błędu związanych z brakiem folderu host/fxr należą:

  • konflikty między pakietami .NET z różnych repozytoriów,
  • niepełna lub przerwana instalacja,
  • problemy z uprawnieniami systemowymi,
  • błędy w konfiguracji zmiennych środowiskowych,
  • specyfika danej dystrybucji Linux skutkująca zamianą pakietów na natywne odpowiedniki.

Diagnoza i identyfikacja źródła problemu

By skutecznie zidentyfikować przyczynę błędu, należy wykonać następujące kroki:

  • Weryfikacja obecności folderów .NET – ls -la /usr/share/dotnet/, ls -la /usr/lib/dotnet/;
  • Analiza zainstalowanych pakietów – apt list --installed | grep dotnet (Ubuntu), dnf list installed | grep dotnet (RPM);
  • Sprawdzenie zmiennych środowiskowych – dotnet --info;
  • Weryfikacja uprawnień systemowych – ls -la, whoami, groups;
  • Analiza dzienników systemowych – cat /var/log/apt/history.log, journalctl;
  • Weryfikacja repozytoriów pakietów – /etc/apt/sources.list.d/, obecność microsoft-prod.list.

Podstawowe rozwiązania problemu

Najskuteczniejsze podejście polega na gruntownym usunięciu wszystkich pakietów .NET oraz ich reinstalacji z jednego, właściwego repozytorium. Zalecane czynności obejmują:

  1. Usunięcie wszystkich pakietów związanych z .NET – sudo apt remove dotnet*, sudo apt remove aspnetcore*, sudo apt remove netstandard*;
  2. Wybór repozytorium pakietów – instalacja z repo Microsoft lub natywnego repozytorium dystrybucji;
  3. Usunięcie pliku microsoft-prod.list po wyborze natywnego repozytorium – pozwala uniknąć konfliktów przy przyszłych aktualizacjach;
  4. Instalacja i aktualizacja .NET – np. sudo apt update oraz sudo apt install dotnet-sdk-6.0;
  5. Konfiguracja priorytetów pakietów (jeśli korzystasz z repo Microsoft) – ustawienie pliku /etc/apt/preferences.d/99microsoft-dotnet.pref z Pin-Priority: 1001;
  6. Weryfikacja działania .NET – dotnet --version, dotnet --list-sdks, dotnet --list-runtimes.

Zaawansowane techniki rozwiązywania problemów

W trudniejszych przypadkach można sięgnąć po dodatkowe, bardziej techniczne metody:

  • Ręczne tworzenie struktury katalogów i dowiązań symbolicznych – znajdź libhostfxr.so poleceniem find /usr -name "libhostfxr.so" 2>/dev/null i utwórz odpowiednie dowiązania symboliczne;
  • Konfiguracja zmiennych środowiskowych – ustawienie DOTNET_ROOT i opcjonalnie MSBuildSDKsPath w profilu powłoki;
  • Instalacja przy użyciu skryptu dotnet-install.sh – pobierz https://dot.net/v1/dotnet-install.sh, nadaj uprawnienia wykonania i zainstaluj wybraną wersję;
  • Wykorzystanie konteneryzacji (Docker, Podman) – pozwala uniknąć konfliktów poprzez pełną izolację środowiska uruchomieniowego .NET.

Specyficzne rozwiązania dla różnych dystrybucji Linux

Zależnie od dystrybucji, postępuj zgodnie z poniższymi wytycznymi:

  • Ubuntu 22.04 i nowsze – konfiguracja priorytetów pakietów, blokowanie automatycznych aktualizacji (99microsoft-dotnet.pref, /etc/apt/apt.conf.d/50unattended-upgrades);
  • CentOS, RHEL, Fedora – usuń dotnet*, zainstaluj ponownie z repozytorium Microsoft (sudo dnf remove dotnet*);
  • Arch Linux – korzystaj z AUR lub oficjalnych pakietów Microsoft, zachowując spójność wersji;
  • NixOS – twórz dowiązania z Nix Store do oczekiwanych ścieżek lub ustaw zmienne środowiskowe;
  • Alpine Linux – używaj obrazów .NET dla musl lub kompiluj samodzielnie;
  • Linux Mint – ustaw DOTNET_ROOT i MSBuildSDKsPath w profilu użytkownika.

Mechanizmy zapobiegania problemom

Aby ograniczyć ryzyko ponownego wystąpienia błędu, stosuj się do poniższych zasad:

  • konsekwentnie korzystaj z jednego źródła pakietów,
  • blokuj automatyczne aktualizacje .NET,
  • twórz kopie zapasowe konfiguracji i plików repozytoriów,
  • regularnie diagnozuj środowisko .NET,
  • notuj wszelkie zmiany i konfiguracje,
  • testuj aktualizacje w izolowanych środowiskach przed wdrożeniem na produkcję,
  • śledź zmiany w zarządzaniu pakietami .NET w swojej dystrybucji

Narzędzia i skrypty automatyzujące

Dedykowane skrypty mogą znacznie przyspieszyć naprawę środowiska .NET. Oto obszary, które warto automatyzować:

  • Sprawdzanie obecności i uprawnień folderów .NET;
  • Analizę zainstalowanych pakietów oraz repozytoriów źródłowych;
  • Szybkie wykrywanie konfliktów i automatyczną reinstalację;
  • Integrację z narzędziami do automatycznej konfiguracji (Ansible, Puppet, Chef);
  • Monitorowanie i automatyczną reakcję na błędy (Nagios, Zabbix, Prometheus);
  • Budowę i wdrażanie obrazów Docker/CI-CD (np. GitLab CI, Azure Pipelines).

Długoterminowe strategie zarządzania

Efektywne zarządzanie środowiskiem .NET w organizacji wymaga wdrożenia strategicznych praktyk:

  • Jasno określ źródło instalacji pakietów (.NET od Microsoft lub z dystrybucji);
  • Standardyzuj środowiska z wykorzystaniem Infrastructure as Code (Terraform, CloudFormation, ARM);
  • Wprowadź CI/CD z automatycznym testowaniem środowiska .NET;
  • Przeprowadzaj migracje oraz regularnie testuj przy zmianach wersji .NET;
  • Zwiększaj kompetencje techniczne zespołu;
  • Uwzględnij współpracę z dostawcami usług chmurowych i rozważ usługi zarządzane;
  • Monitoruj i analizuj aplikacje .NET za pomocą zaawansowanych narzędzi telemetrii (Application Insights, New Relic, Datadog).

Rekomendacje i najważniejsze wnioski

Na podstawie zgromadzonej wiedzy rekomenduje się:

  • Błąd „[/usr/share/dotnet/host/fxr] does not exist” stanowi przejaw głębszych problemów z zarządzaniem środowiskiem .NET na Linuksie;
  • Unikaj mieszania repozytoriów Microsoft i natywnych dystrybucji;
  • Monitorowanie, automatyzacja i testowanie są kluczowe dla stabilności wdrożeń;
  • Dla Ubuntu 22.04 i nowszych: konieczna jest właściwa konfiguracja priorytetów oraz blokada automatycznych aktualizacji;
  • Konteneryzacja aplikacji .NET to najbardziej stabilna, długoterminowa strategia;
  • Stwórz proces ciągłego szkolenia i rozwoju kompetencji technicznych swojego zespołu;
  • Korzystanie z usług zarządzanych takich jak Azure App Service czy AWS Lambda upraszcza infrastrukturę i ogranicza ryzyko błędów;
  • Zarządzanie środowiskiem .NET w sposób całościowy zapewnia długofalową przewagę konkurencyjną.