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
Applies to
Product: Server · Audience: Platform Operator
Common failure patterns and their diagnosis – symptom, likely cause, solution. This page consolidates the troubleshooting sections of the installation pages, the FAQ and the Helm reference. Start with the basic commands, then look up your symptom in the tables.
Basic commands
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 # or -l app.kubernetes.io/name=<service>
kubectl -n basebox logs <pod> --previous # after restart
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
Internal connectivity test from a debug pod:
kubectl run -it --rm debug --image=busybox --restart=Never -n basebox -- sh
# inside the pod:
wget -qO- http://aisrv:8888/health; wget -qO- http://inference:8000/health
Pods and cluster
| Symptom | Cause | Solution |
|---|---|---|
Pods Pending |
No GPU/MIG resource free, no storage class, control-plane taint | kubectl describe pod (events); describe node Allocatable; get pvc; tolerations or taint (Kubernetes) |
CrashLoopBackOff |
Configuration error, missing secret, database unreachable | logs --previous; check secrets (get secrets); DB pods Running? |
ImagePullBackOff |
Registry access of the node runtime | Test the pull from the runtime, not just from the workstation; pull secret |
inference/ragsrv-support: "Temporary error in name resolution" |
k3s with systemd-resolved | Point coredns at an external DNS – FAQ |
| Database connection fails | DB cluster not ready, wrong secret | get cluster; logs <db-pod>; secret *-database |
GPU Operator pods Pending, "untolerated taint" |
Single node | Tolerations values (NVIDIA / GPU) |
helm install "context deadline exceeded" |
Large images, slow download | --timeout 15m/120m; recreate namespace; watch pods |
GPU
| Symptom | Cause | Solution |
|---|---|---|
nvidia-smi not found / "couldn't communicate with driver" |
Driver missing or incomplete | sudo apt-get purge nvidia-*, ubuntu-drivers autoinstall, reboot |
Node advertises no nvidia.com/gpu |
GPU Operator not ready, driver conflict | get pods -n gpu-operator; logs; node labels |
| MIG resources missing after reboot | MIG layout not persistent, discovery not mixed |
Recreate MIG; check MIG strategy; restart device plugin |
| OOM in inference logs | Model + KV cache > VRAM | Lower context, quantise KV cache, quantise more strongly, TP – Scaling |
| GPU throttles (temperature) | Cooling, power budget | nvidia-smi dmon; manufacturer/FAST LTA approval |
| Data parallelism produces nonsense (GPT-OSS 120B) | Known issue | Use tensor parallelism |
Decision trees: Server Preparation Guide → Troubleshooting.
Login and interface
| Symptom | Cause | Solution |
|---|---|---|
| "Organisation not found" instead of the login page | VITE_BB_OIDC_FORCE_REALM missing |
Set to primary |
| Only a loading spinner | Frontend cannot reach backend/IdP | Browser console (F12); VITE_BB_GRAPHQL_URL, VITE_BB_OIDC_DOMAIN |
/auth/… 404 in the console |
IdP path wrong | VITE_BB_OIDC_DOMAIN = https://<domain>/auth/realms/ with trailing slash; check .well-known/openid-configuration |
| Redirect loop after login | Auth fails at an unexpected point; global.domain ≠ external hostname |
Clear browser data; console (INVALID_TOKEN); aisrv logs |
aisrv: "iss does not match" |
AISRV_OIDC_IDP_URL not a base URL or ≠ VITE_BB_OIDC_DOMAIN |
Align; set AISRV_OIDC_ISSUER_URL only with care – a foreign issuer would admit foreign tokens |
404 on the hostname |
DNS ≠ ingress host | Compare DNS and kubectl get ingress |
| Certificate not issued | ClusterIssuer, ACME reachability | get certificate,certificaterequest,order,challenge |
| GraphQL returns HTML | Ingress rules/host | Check ingress paths |
| Support button missing/wrong | VITE_BB_SUPPORT_BUTTON_LINK |
Set URL or leave empty to hide |
Chat, inference, RAG
| Symptom | Cause | Solution |
|---|---|---|
| "data transmission failed (SSE)" | Connection browser↔server or AISRV↔inference/ragsrv; proxy buffers | aisrv logs; disable proxy buffering, timeouts; inference health |
| Chat does not answer, error visible | Inference offline (no fallback) | Check inference pod/endpoint; wait for warm-up after start |
| "Model not found" | AISRV_LLM_MODEL ≠ /v1/models |
Copy the identifier exactly |
| 401 from the inference endpoint | Keys differ | AISRV_LLM_API_KEY and VLLM_API_KEY from the same secret |
| Long requests abort | AISRV_LLM_CONTEXT_SIZE > runtime context |
Align the values |
| Train of thought in the answer text | Reasoning parser missing | Configure the parser in vLLM |
| Uploads stay "processing" | ragsrv ↔ ragsrv-support (API_KEY), webhook | Logs of both; WEBHOOK_STATE_URL = http://aisrv:8888/rag/v1/state |
| OCR/STT very slow | CPU mode or shared GPU | Dedicated GPU/MIG |
| Connector "Test connection" fails | Base URL, egress, TLS CA | Connector pod logs; firewall to the target system; import private CA |
Storage and database
| Symptom | Cause | Solution |
|---|---|---|
PVC Pending |
Storage class missing/not default | get storageclass; set in values |
| Uploads/downloads fail | Volume full | Enlarge PVC; clear caches |
| CNPG cluster not healthy | Storage, replication | describe cluster; DB logs; check backup |
| Migration fails on start | Checksum, incompatible state | Logs (grep migrat); restore from backup – Updates |
If nothing helps
- Note symptom, time, recent changes.
- Collect
aisrvlogs and logs of the affected component,get events, browser console, manifest – without credentials. - support@basebox.ai; for suspected security issues datenschutz@basebox.ai.
Further collections: FAQ · Helm chart overview → Troubleshooting · Using Helm charts → Troubleshooting