Debugging und Fehlersuche
Quelle: pkr-lab/pkr-lab-docs/ui-terminal-config/debugging.md
Debugging und Fehlersuche
Code: install.sh, starship-toml-template
Das Projekt hat kein Log und keinen Dienst. Alle Ausgaben stehen im Terminal, install.sh kennzeichnet sie mit [OK], [SKIP], [INFO] und [ERROR]. Zum genauen Nachverfolgen hilft bash -x ./install.sh (zeigt jeden Befehl). Das projektübergreifende Kapitel ist die zentrale Fehlersuche.
Meldungen von install.sh
| Meldung | Ursache | Lösung |
|---|---|---|
[SKIP] starship (already installed) |
Starship ist im PATH |
kein Fehler. Die Version aktualisiert man mit curl -sS https://starship.rs/install.sh \| sh -s -- --yes --bin-dir ~/.local/bin |
[SKIP] starship.toml (already linked) |
Symlink zeigt schon auf die Vorlage | kein Fehler |
[INFO] Backing up existing starship.toml to … |
eine eigene Konfiguration lag vor | Sicherung liegt neben der Datei, bei Bedarf zurückkopieren |
[INFO] npm global prefix (…) isn't writable; switching to /home/…/.local |
globales npm-Verzeichnis nicht beschreibbar | Hinweis: Das Skript setzt npm config set prefix ~/.local. Rückgängig mit npm config delete prefix |
[ERROR] <befehl> -- npm not found, install Node.js first |
npm fehlt, aber eine KI-CLI wurde angefordert |
sudo apt install nodejs npm, Skript erneut starten. Das Skript läuft nach dieser Meldung weiter, die CLI fehlt aber |
[SKIP] claude (set INSTALL_CLAUDE=true to install) (analog codex, gemini, agy) |
Variable steht auf false |
gewollt, oder Variable auf true setzen |
[SKIP] <befehl> (already installed) |
Programm ist bereits im PATH |
kein Fehler |
[INFO] Installing unzip (needed to unpack the font) ... |
unzip fehlt |
Skript nutzt sudo apt-get install -y unzip, fragt ggf. nach dem sudo-Passwort |
[SKIP] JetBrainsMono Nerd Font already installed |
fc-list findet die Schrift |
kein Fehler |
[OK] Done. |
alles durchgelaufen | – |
Abbruch ohne eigene [ERROR]-Meldung (das Skript läuft mit set -euo pipefail):
| Symptom | Ursache | Lösung |
|---|---|---|
curl: (6) Could not resolve host oder curl: (22) |
kein Netz, Proxy oder URL nicht erreichbar | Verbindung prüfen. Die Installer kommen von starship.rs, github.com/ryanoasis/nerd-fonts und antigravity.google |
sudo: a password is required |
unzip soll installiert werden, aber sudo ohne Terminal |
in einem Terminal starten oder unzip vorher installieren |
unzip: cannot find or open … oder Abbruch beim Download der Schrift |
Download unvollständig | Skript erneut ausführen, ein temporärer Fehler wird dadurch behoben |
npm ERR! code EACCES |
Berechtigungen im npm-Verzeichnis | Skript neu starten, es stellt den Präfix selbst auf ~/.local, falls das Verzeichnis nicht beschreibbar ist |
Abbruch bei npm install -g … |
Paket nicht gefunden oder npm-Fehler | npm install -g <paket> direkt ausführen und die Fehlermeldung lesen |
Fehlerbilder im Terminal
| Symptom | Ursache | Lösung |
|---|---|---|
| Prompt unverändert | Starship nicht in der Shell aktiviert | eval "$(starship init bash)" in ~/.bashrc, neue Shell öffnen |
starship: command not found |
~/.local/bin nicht im PATH |
export PATH="$HOME/.local/bin:$PATH" in ~/.bashrc |
Kästchen oder ? statt Symbolen im Prompt |
Terminal nutzt nicht die Nerd Font | Schrift JetBrainsMono Nerd Font Mono im Terminal einstellen, fc-list \| grep -i "JetBrainsMono.*Nerd" muss einen Treffer liefern |
| Symbole sehen versetzt aus | Schrift ohne „Mono“-Variante | JetBrainsMono Nerd Font Mono wählen |
Schrift in fc-list vorhanden, Terminal zeigt sie nicht |
Schrift-Cache veraltet | fc-cache -f ~/.local/share/fonts, Terminal neu starten |
Segment fehlt in großen Git-Repos (mit STARSHIP_LOG=warn steht Executing command … timed out) |
Git-Abfrage braucht länger als command_timeout (5000 ms) |
command_timeout in der Vorlage erhöhen |
| Verzeichnis zeigt fehlende Sprach-Segmente | Datei, die das Segment erkennt, liegt tiefer als scan_timeout (100 ms) erlaubt |
scan_timeout erhöhen |
| Kein Docker-Segment | $docker_context fehlt in format |
siehe Konfiguration |
starship config meldet unbekannte Schlüssel |
neuere Starship-Version ändert Schlüssel | starship config bzw. starship print-config prüfen, Starship-Dokumentation |
| Konfiguration wirkt nicht | Symlink zeigt ins Leere (Checkout verschoben) | ls -l ~/.config/starship.toml, ./install.sh im neuen Checkout erneut ausführen |
claude: command not found nach der Installation |
~/.local/bin nicht im PATH (npm-Präfix wurde auf ~/.local gesetzt) |
PATH ergänzen |
| Alte Konfiguration wiederherstellen | – | mv ~/.config/starship.toml.bak.<Zeitstempel> ~/.config/starship.toml (den Symlink vorher entfernen) |
Checkliste „Prompt oder Schrift funktioniert nicht“
command -v starshipundstarship --version: gefunden?ls -l ~/.config/starship.toml: Symlink auf die Vorlage im Checkout, Ziel existiert?tail ~/.bashrc: stehteval "$(starship init bash)"darin?fc-list | grep -i "JetBrainsMono.*Nerd": Schrift installiert?- Terminal-Einstellungen: ist
JetBrainsMono Nerd Font Monogewählt? STARSHIP_LOG=trace starship prompt 2>&1 | headzeigt, welches Segment wie lange braucht und welche Fehler Starship sieht.bash -x ./install.sh: welcher Schritt bricht ab?
Allgemeines zur Installation: Installation.