Troubleshooting#
Diagnose one layer at a time: cluster connection, required APIs/operators, storage, database initialization, application readiness, routing, then browser/API access. Do not change credentials or disable TLS to work around an unrelated startup problem.
In the commands below, set BASYX_CONTEXT to your actual context. Examples use namespace basyx-evaluation; substitute your assigned namespace if it differs.
Cluster and chart selection#
Symptom |
Check |
Next action |
|---|---|---|
Connection refused, unauthorized, or certificate error before listing pods |
|
Fix the cluster connection with the cluster operator. Application values cannot fix a Kubernetes API certificate mismatch. |
Helm cannot find a chart/version |
|
Confirm the Go chart reference |
Template/schema error |
Selected chart version and exact values keys |
Compare against |
Ingress or certificate cannot become ready |
Remaining placeholders in your overlay |
Replace |
Resource already exists or has different ownership |
Existing releases, fixed resource names, and namespace |
Check |
Database and startup#
kubectl --context "$BASYX_CONTEXT" -n basyx-evaluation get pods,jobs,pvc
kubectl --context "$BASYX_CONTEXT" -n basyx-evaluation get clusters.postgresql.cnpg.io
kubectl --context "$BASYX_CONTEXT" -n basyx-evaluation get events \
--sort-by=.metadata.creationTimestamp
Symptom |
Likely layer |
What to inspect |
|---|---|---|
PVC is |
Storage |
StorageClass, provisioner events, available capacity, and volume binding/scheduling. |
PostgreSQL pods cannot schedule |
Cluster capacity/topology |
Resource requests, node/zone labels, affinity, and PVC placement. |
Configuration Job stays in its wait init container |
Database readiness |
CloudNativePG status and the configured database address/Secret. |
Job fails after reaching PostgreSQL |
Schema, permissions, or configuration |
Initializer logs and the Go Configuration Service error. |
First install times out with |
Hook ordering |
The Go schema initializer is post-install. Follow the non-waiting first-install procedure and inspect the existing failed release before retrying. |
|
Image access |
Image repository, exact tag/digest, credentials, registry access, and architecture support. |
Runtime rejects the schema |
Version alignment/state |
Compatible runtime/initializer images and schema state. Do not delete the database to make a production service start. |
Inspect the initializer while its Job still exists:
kubectl --context "$BASYX_CONTEXT" -n basyx-evaluation describe job basyx-configuration
kubectl --context "$BASYX_CONTEXT" -n basyx-evaluation logs \
job/basyx-configuration --all-containers --tail=100
A completed Job may later disappear because of its TTL. If a migration failed, use Configuration Service operational guidance rather than repeatedly retrying without checking database state.
Browser, routing, and TLS#
Symptom |
What it means to check |
|---|---|
Ingress returns 404 |
Host header/DNS, IngressClass, controller status, configured path, and backend Service/port. |
HTTPRoute does not work |
Gateway/controller availability, listeners, namespace permissions, |
TLS certificate is untrusted |
Correct CA trust and issuance. A lab CA is not automatically trusted. |
Certificate hostname mismatch |
The certificate must cover the hostname used in the browser/API address. An unexpired wildcard certificate does not match arbitrary nested subdomains. |
UI loads, but its API calls fail |
Browser-facing infrastructure URLs, CORS, active API services, and application authorization. A page loading is not an API health test. |
UI asks for sign-in although Keycloak was disabled |
UI infrastructure still has OAuth enabled. Use |
A fresh UI shows no AAS |
Check the API directly. An empty database is expected until you import/create data. |
Compare the browser-facing host in host and tls.hosts with DNS, the certificate, and the Web UI’s infrastructure URLs. The walkthrough uses one HTTPS hostname with /aas-gui/ for the UI and /aas-environment/ for the API; internal Kubernetes Service names are not browser addresses.
Asking for help#
Provide the chart name/version, Helm version, Kubernetes/operator versions, deployment shape, sanitized values excerpt, exact command/error, relevant pod/Job events, and whether the failure is in cluster access, startup, or browser traffic.
Use the BaSyx chart issue tracker for chart problems, and the Go component documentation for application-specific behavior. Include a minimal reproducible example and remove private infrastructure details and secrets first.