bash install.sh status, and find fixes by symptom under Troubleshooting.
Backups
The chart creates no backup job. Back up these volumes yourself, for example with AWS Backup or EBS snapshots:Monitoring
No metrics stack orServiceMonitor ships. The xpander-smoke Job logs smoke passed: every required component serves when all components answer, and bash install.sh status gives a read-only verdict. Scrape the services with your own stack for metrics.
Troubleshooting
Every failure printsFIX: (the repair) and RERUN: (your non-interactive one-liner, secrets as placeholders). The installer is idempotent: fix, paste the rerun line, and it resumes. The checklist stops most problems before anything changes. Scripts read the exit code (Automation & CI), and bash install.sh status gives a read-only verdict.
Mirroring and registries
Mirror push fails: name unknown, 'The repository ... does not exist' (ECR)
Mirror push fails: name unknown, 'The repository ... does not exist' (ECR)
image_sync.sh creates them (with AWS CLI credentials). Refresh your copy:Mirror push fails: authentication required at the destination
Mirror push fails: authentication required at the destination
authentication required even though docker login works: skopeo cannot read Docker Desktop’s credential store. The current image_sync.sh logs in to ECR itself (aws ecr get-login-password | skopeo login --username AWS --password-stdin). For other registries, pass credentials:401 from Docker Hub when resolving or mirroring
401 from Docker Hub when resolving or mirroring
401 from auth.docker.io (incorrect username or password): the credential is the organization username xpanderaihub plus the token from your email, not a personal username. Re-run with --xpander-registry-user xpanderaihub --xpander-registry-token <token>. Still refused? Ask xpander to re-issue the token with repository-read and image-pull access.Pods can't pull: manifest unknown at your pinned tag
Pods can't pull: manifest unknown at your pinned tag
manifest unknown, or the checklist reports:image_sync.sh), then check the exact coordinate:Cluster and network
Nodes time out pulling from docker.io (dial tcp ... i/o timeout)
Nodes time out pulling from docker.io (dial tcp ... i/o timeout)
docker.io instead of your mirror. Install with --registry <your-mirror>/<path>, and make sure the nodes reach the mirror (on an ECR-only sealed VPC: ecr.api + ecr.dkr endpoints, the S3 gateway endpoint, ECR read on the node role). Find the reference:Preflight: no node with a supported architecture (Graviton/ARM)
Preflight: no node with a supported architecture (Graviton/ARM)
exec format error.) xpander images are amd64-only, so ARM/Graviton (t4g, m7g, c7g, …) cannot run them. Add an amd64 node group. Only for genuinely arm64 images: --set 'preflight.allowedArchitectures[0]=arm64'.LoadBalancer Service stuck <pending>: could not find any suitable subnets
LoadBalancer Service stuck <pending>: could not find any suitable subnets
kubectl -n xpander port-forward svc/ui 8080:80.External data-tier probe fails: namespaces 'xpander' not found
External data-tier probe fails: namespaces 'xpander' not found
curl -fsSL https://charts.xpander.ai/install.sh) or create the namespace and re-run:Pods stuck in Pending
Pods stuck in Pending
kubectl -n xpander describe pvc) mean no usable RWO StorageClass or too little capacity for the footprint. Check kubectl get storageclass, pass --storage-class <name>, and look for FailedScheduling in kubectl -n xpander get events --sort-by=.lastTimestamp.UI loads blank: Missing or invalid environment variables
UI loads blank: Missing or invalid environment variables
bash install.sh upgrade, or set ui.env (VITE_SUPABASE_URL, VITE_CHAT_BACKEND_URL, …) yourself.Only the UI host resolves. Other subdomains 404 or NXDOMAIN
Only the UI host resolves. Other subdomains 404 or NXDOMAIN
chat.<domain> opens but sign-in or API calls fail: only one of the published hosts has a record. Add a wildcard *.<domain>, or records for chat, api, agent-controller, supabase, webhook, client-auth and actions (or your <name>.ingress.host values). Check what is published:Install and upgrade
Release stuck in pending-install / pending-upgrade / failed
Release stuck in pending-install / pending-upgrade / failed
install.sh upgrade needs deployed. Recover first:RERUN: line. pending-install (an interrupted first install) is fixed with helm uninstall. xpander-generated-keys survives it, so the reinstall keeps the same keys.'images are unpinned' / chart refuses to render
'images are unpinned' / chart refuses to render
License expired or rejected
License expired or rejected
xpander-license/v2 files (or the legacy v1 file) and the --org binding. Preflight repeats it with the Ed25519 signature, and deployment-manager repeats it at boot. GET /v1/license/status answers valid, expiring, grace or expired.Expired: the installer warns License expired on <date> - preflight will refuse the install. Replace only activation.json in the Secret with the renewed file and redeploy:install.sh upgrade or your pipeline’s re-install (the Secret checksum rolls the services). Keep the --set global.license.installKey/activationKey/publicKey flags if you pass your own --values (The License). A legacy v1 install swaps its license.json the same way.An agent answers 500 Failed to build agent details
An agent answers 500 Failed to build agent details
faulty, no spec). The agents pod log shows a pydantic error on ConnectedConnector.open_api_spec_id. Recover from the in-cluster Supabase database:A pipeline stage failed (preflight / keygen / migrations / org-seed / smoke)
A pipeline stage failed (preflight / keygen / migrations / org-seed / smoke)
--org-name and --admin-email whenever Supabase is on. A hand-driven helm upgrade without them fails at render time.Services fail auth after an upgrade with a custom values file
Services fail auth after an upgrade with a custom values file
password: "" beside it overrides the generated password with an empty string. Remove the empty password: key: an absent key is preserved, "" wins.Creating a skill from an OpenAPI spec stops at "Generating the enriched spec", but the skill appears anyway
Creating a skill from an OpenAPI spec stops at "Generating the enriched spec", but the skill appears anyway
Pods in ImagePullBackOff after an upgrade
Pods in ImagePullBackOff after an upgrade
manifest unknown). Mirror the target release and re-run the upgrade. --atomic already rolled back the failed attempt.Edge-runtime crash-looping after upgrading with --reuse-values
Edge-runtime crash-looping after upgrading with --reuse-values
--reuse-values resurrected a stale edge-runtime image pin. Upgrade with your real values files (as install.sh upgrade does), or clear it once:--edge-functions-tag).Release already runs the other deployment's chart
Release already runs the other deployment's chart
--release / --namespace, or helm uninstall xpander -n xpander first.Piped run exits with 'these required flags are missing'
Piped run exits with 'these required flags are missing'
bash, the run is non-interactive and needs --org, --install-license-file and --activation-license-file (or --license-file for v1). It exits with code 2 and a rerun line. For the wizard, download the script and run bash install.sh --edition airgap.
