Troubleshooting

Pod startup errors

Symptom	Cause	Fix
ImagePullBackOff on web-app	Image not in registry or pull secret missing	For Path 0: run k3d image import. For Path ½: verify app-registrycreds in 02-secrets.yaml
ImagePullBackOff on xtra-wasm	hopr-registrycreds missing or empty	Verify hopr-registrycreds in 02-secrets.yaml — check it has a non-empty .dockerconfigjson value
ErrImageNeverPull	imagePullPolicy: Never but image not imported	Run k3d image import <image-tag> -c <cluster> with the exact tag in 03-deployment.yaml
CrashLoopBackOff on xtra-wasm	Missing or invalid Hopr credentials	Open 02-secrets.yaml and verify all four fields are non-empty: HOPR_LICENSE, HOPR_KEY, CHIPS_ALGORITHM, HOPR_API_TOKEN
Pod stuck at 2/3 Ready	One container (xtra-wasm or web-retriever) failing	Run kubectl describe pod <pod-name> -n <namespace> and check the Events section

WoSP connectivity errors

Symptom	Cause	Fix
Auto-trigger logs but no 5/5 messages sent	Downstream pod not ready or WoSP authentication failed	Wait 60–90 seconds after kubectl apply for WoSP to complete authentication; check xtra-wasm logs
connection refused in web-app logs	Egress port misconfigured or pod not reachable	Verify EGRESS_PORT env var in 03-deployment.yaml matches the downstream pod's WoSP ingress port
No CYCLE COMPLETE / no trail entries	Cross-pod message delivery failing	Check xtra-wasm logs on the receiving pod; look for WoSP authentication errors
503 Service Unavailable from Envoy	WoSP filter rejecting the request	Credentials may be expired — check license status and verify HOPR_API_TOKEN is current

Multi-cluster errors

Symptom	Cause	Fix
connection refused on host.k3d.internal	Port not mapped at cluster creation	Delete cluster and recreate with correct --port flags — mappings cannot be added after creation
DNS resolution failure	k3d < 5.0	Upgrade k3d to >= 5.0 which supports host.k3d.internal
Cross-cluster trail shows only one cluster	LoadBalancer IP not reachable from other cluster	Verify the --port flag maps the correct LoadBalancer port; test with curl http://host.k3d.internal:<port>/health
<pending> on LoadBalancer service (cloud)	Cloud provisioning delay	Wait 2–5 minutes; if persists, check cloud provider quotas and LoadBalancer permissions

Credential errors

Symptom	Cause	Fix
WoSP logs license validation failed	Invalid or expired HOPR_LICENSE	Check license status at hopr.co; contact support if active
WoSP logs key rotation failed	HOPR_API_TOKEN invalid or network blocked	Verify the token in 02-secrets.yaml; ensure the pod has outbound internet access
Empty 02-secrets.yaml values	Delivery error — credentials not injected	Contact support@hopr.co with your Customer ID

Build errors (Path 0)

Symptom	Cause	Fix
docker: command not found	Docker not installed or not running	Start Docker Desktop
k3d: command not found	k3d not installed	Install from k3d.io
Image imported but pod still shows ErrImageNeverPull	Tag mismatch	Ensure docker build -t <tag> matches the image: field in 03-deployment.yaml