Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.
Licensed to be used in conjunction with basebox, only.
// installation
Troubleshooting
Gilt für
Produkt: Server · Zielgruppe: Platform Operator
Häufige Fehlerbilder und ihre Diagnose – Symptom, wahrscheinliche Ursache, Lösung. Diese Seite führt die Troubleshooting-Abschnitte der Installationsseiten, der FAQ und der Helm-Referenz zusammen. Beginnen Sie mit den Grundbefehlen, dann suchen Sie Ihr Symptom in den Tabellen.
Grundbefehle
kubectl -n basebox get pods -o wide
kubectl -n basebox get events --sort-by='.lastTimestamp' | tail -30
kubectl -n basebox describe pod <pod>
kubectl -n basebox logs <pod> --tail=200 # oder -l app.kubernetes.io/name=<dienst>
kubectl -n basebox logs <pod> --previous # nach Neustart
kubectl -n basebox get pvc,cluster,ingress,secret
kubectl top pods -n basebox; kubectl top nodes
kubectl describe node <node> | grep -A8 -E "Allocatable|Allocated resources"
nvidia-smi; nvidia-smi -L
Interner Verbindungstest aus einem Debug-Pod:
kubectl run -it --rm debug --image=busybox --restart=Never -n basebox -- sh
# im Pod:
wget -qO- http://aisrv:8888/health; wget -qO- http://inference:8000/health
Pods und Cluster
| Symptom | Ursache | Lösung |
|---|---|---|
Pods Pending |
Keine GPU-/MIG-Ressource frei, keine Storage Class, Control-Plane-Taint | kubectl describe pod (Events); describe node Allocatable; get pvc; Tolerations oder Taint (Kubernetes) |
CrashLoopBackOff |
Konfigurationsfehler, fehlendes Secret, Datenbank nicht erreichbar | logs --previous; Secrets prüfen (get secrets); DB-Pods Running? |
ImagePullBackOff |
Netzzugang der Knoten-Runtime zur Registry | Pull aus der Runtime testen, nicht nur von der Workstation; Netzzugang zu gitea.basebox.health bzw. zu Ihrem internen Mirror |
inference/ragsrv-support: „Temporary error in name resolution" |
k3s mit systemd-resolved | coredns auf externen DNS zeigen lassen – FAQ |
| Datenbankverbindung scheitert | DB-Cluster nicht bereit, falsches Secret | get cluster; logs <db-pod>; Secret *-database |
GPU-Operator-Pods Pending, „untolerated taint" |
Einzelknoten | Tolerations-Values (NVIDIA / GPU) |
helm install „context deadline exceeded" |
Große Images, langsamer Download | --timeout 15m/120m; Namespace neu; Pods beobachten |
GPU
| Symptom | Ursache | Lösung |
|---|---|---|
nvidia-smi nicht gefunden / „couldn't communicate with driver" |
Treiber fehlt oder unvollständig | sudo apt-get purge nvidia-*, ubuntu-drivers autoinstall, Neustart |
Knoten bietet keine nvidia.com/gpu an |
GPU Operator nicht bereit, Treiber-Konflikt | get pods -n gpu-operator; Logs; Knoten-Labels |
| MIG-Ressourcen fehlen nach Neustart | MIG-Layout nicht persistent, Erkennung nicht mixed |
MIG erneut anlegen; MIG-Strategie prüfen; Device-Plugin neu starten |
| OOM in Inferenz-Logs | Modell + KV-Cache > VRAM | Kontext senken, KV-Cache quantisieren, stärker quantisieren, TP – Skalierung |
| GPU drosselt (Temperatur) | Kühlung, Leistungsbudget | nvidia-smi dmon; Hersteller-/FAST-LTA-Freigabe |
| Datenparallelismus erzeugt Unsinn (GPT-OSS 120B) | Bekanntes Problem | Tensor-Parallelismus nutzen |
Entscheidungsbäume: Server vorbereiten → Troubleshooting.
Login und Oberfläche
| Symptom | Ursache | Lösung |
|---|---|---|
| „Organisation not found" statt Anmeldeseite | VITE_BB_OIDC_FORCE_REALM fehlt |
Auf primary setzen |
| Nur ein Ladekreis | Frontend erreicht Backend/IdP nicht | Browser-Konsole (F12); VITE_BB_GRAPHQL_URL, VITE_BB_OIDC_DOMAIN |
/auth/… 404 in der Konsole |
IdP-Pfad falsch | VITE_BB_OIDC_DOMAIN = https://<domain>/auth/realms/ mit Schrägstrich; .well-known/openid-configuration prüfen |
| Weiterleitungsschleife nach Login | Auth scheitert an unerwarteter Stelle; global.domain ≠ externer Hostname |
Browserdaten löschen; Konsole (INVALID_TOKEN); aisrv-Logs |
aisrv: „iss does not match" |
AISRV_OIDC_IDP_URL keine Basis-URL oder ≠ VITE_BB_OIDC_DOMAIN |
Angleichen; nur mit Bedacht AISRV_OIDC_ISSUER_URL setzen – ein fremder Issuer ließe fremde Tokens zu |
404 auf dem Hostname |
DNS ≠ Ingress-Host | DNS und kubectl get ingress vergleichen |
| Zertifikat wird nicht ausgestellt | ClusterIssuer, ACME-Erreichbarkeit | get certificate,certificaterequest,order,challenge |
| Sicherheitswarnung im Browser, auf anderen Geräten nicht | Gerät vertraut der internen CA nicht, etwa weil es nicht in der Domäne ist | Stammzertifikat der CA auf dem Gerät importieren; siehe Client-Geräte müssen der ausstellenden CA vertrauen |
| GraphQL liefert HTML | Ingress-Regeln/Host | Ingress-Pfade prüfen |
| Support-Schaltfläche fehlt/falsch | VITE_BB_SUPPORT_BUTTON_LINK |
URL setzen oder leer lassen zum Ausblenden |
Chat, Inferenz, RAG
| Symptom | Ursache | Lösung |
|---|---|---|
| „data transmission failed (SSE)" / „Fehler bei der Datenübertragung" | Verbindung Browser↔Server oder AISRV↔Inferenz/ragsrv; Proxy puffert | aisrv-Logs; Proxy-Pufferung aus, Timeouts; Inferenz-Health |
| Chat antwortet nicht, Fehler sichtbar | Inferenz offline (kein Rückfall) | Inferenz-Pod/Endpunkt prüfen; nach Start Warm-up abwarten |
| „Model not found" | AISRV_LLM_MODEL ≠ /v1/models |
Bezeichner exakt übernehmen |
| 401 vom Inferenz-Endpunkt | Schlüssel ungleich | AISRV_LLM_API_KEY und VLLM_API_KEY aus demselben Secret |
| Lange Anfragen brechen ab | AISRV_LLM_CONTEXT_SIZE > Runtime-Kontext |
Werte angleichen |
| Gedankengang im Antworttext | Reasoning-Parser fehlt | Parser in vLLM konfigurieren |
| Uploads bleiben „in Verarbeitung" | ragsrv ↔ ragsrv-support (API_KEY), Webhook | Logs beider; WEBHOOK_STATE_URL = http://aisrv:8888/rag/v1/state |
| OCR/STT sehr langsam | CPU-Modus oder geteilte GPU | Dedizierte GPU/MIG |
| Konnektor „Verbindung testen" scheitert | Basis-URL, Egress, TLS-CA | Konnektor-Pod-Logs; Firewall zum Zielsystem; private CA importieren |
Speicher und Datenbank
| Symptom | Ursache | Lösung |
|---|---|---|
PVC Pending |
Storage Class fehlt/nicht Standard | get storageclass; in Values setzen |
| Uploads/Downloads scheitern | Volume voll | PVC vergrößern; Caches leeren |
| CNPG-Cluster nicht healthy | Speicher, Replikation | describe cluster; DB-Logs; Backup prüfen |
| Migration scheitert beim Start | Prüfsumme, inkompatibler Stand | Logs (grep migrat); aus Backup wiederherstellen – Updates |
Wenn nichts hilft
- Symptom, Zeitpunkt, letzte Änderungen notieren.
aisrv-Logs und Logs der betroffenen Komponente,get events, Browser-Konsole, Manifest sammeln – ohne Zugangsdaten.- support@basebox.ai; bei Sicherheitsverdacht datenschutz@basebox.ai.
Weitere Sammlungen: FAQ · Helm-Chart-Übersicht → Troubleshooting · Helm Charts verwenden → Troubleshooting
Nächster Schritt: FAQ