Troubleshooting

Start on the container detail page. It shows the status, pod state, restart count, recent logs, and the assigned IPv6 address when one exists.

Container is pending or provisioning

Provisioning waits for Kubernetes resources and an IPv6 LoadBalancer address.

If it stays pending for more than a few minutes:

Check Billing for payment or capacity issues.
Check whether the org is past due or suspended.
Delete failed containers you no longer need, because they still reserve capacity.
Try again with a known-good public image such as traefik/whoami:v1.10, which runs unprivileged on a read-only root filesystem and needs no configuration.

Image pull errors

Common causes:

The image reference has a typo.
The image is private.
The tag does not exist.
The registry is temporarily unavailable.

Use a fully qualified public image reference when in doubt:

docker.io/library/nginx:1.25-alpine

Private registry credentials are not supported in simple mode yet.

Container starts and then fails

Open the container detail page and read Pod state and Logs.

Common causes:

The image expects to run as root.
The process writes to /, but simple mode uses a read-only root filesystem.
The process needs Linux capabilities that are dropped by the restricted security context.
The app exits immediately because a required environment variable is missing.
The app listens on a port other than 80 in simple mode.
The process exceeds the 1Gi memory limit and is killed.

Fix the image or config, then use Save & restart or Restart container.

Changes are saved but not live

Editing a container saves desired config first. The running pod changes only after a restart.

Use Save & restart on the edit screen, or use Restart container from the detail page.

DNS does not resolve

Check the AAAA record:

dig AAAA app.example.com

Make sure the record value exactly matches the IPv6 address on the container detail page. If you deleted, recreated, or renamed the container, the address may have changed.

DNS resolves but the service is unreachable

Check IPv6 from your client:

curl -6 https://test-ipv6.com/

Then test the service directly:

curl -6 http://[2a01:4f8:c2c:1234::5]/

If the raw IPv6 address works but the hostname does not, the issue is DNS. If neither works, check the container status and logs.

kubectl LoadBalancer has an EXTERNAL-IP but connection is refused

Symptoms: kubectl get svc shows an EXTERNAL-IP, but curl -6 http://[<EXTERNAL-IP>]/ is refused and a Cloudflare-proxied AAAA returns 523 (origin unreachable), while in-cluster checks (kubectl exec) succeed.

This means the platform ingress policy for your LoadBalancer Service has not been applied yet. DollarBox reconciles an allow-lb-<service> NetworkPolicy for each tenant LoadBalancer automatically, on a sweep that runs every five minutes — so wait that long after kubectl apply before assuming something is wrong. Things to check:

The Service is type: LoadBalancer (a ClusterIP Service is never exposed externally by design).
The Service has a selector that matches your pods, and the ingress is opened on the Service's targetPort.
EXTERNAL-IP is set (not <pending>). Tenant address pools do not auto-assign, so an address only appears if you requested one of your reserved addresses — see below.

If it is still refused well after five minutes, and the pod itself answers over kubectl exec, that is worth reporting.

kubectl rejects my LoadBalancer Service

Every tenant LoadBalancer must ask for one of your organisation's reserved IPv6 addresses by annotation. Admission control rejects the Service outright otherwise:

LoadBalancer Services must request an address from your reserved IPv6 allocation
via the metallb.io/loadBalancerIPs annotation.

or, if you asked for an address that is not yours:

Requested LoadBalancer address is not in your reserved IPv6 allocation.

The annotation is metallb.io/loadBalancerIPs. List your reserved addresses from the Reserved IPv6 addresses card on the kubectl page, or from the ConfigMap the platform keeps in your namespace:

kubectl get configmap container-reserved-ipv6 -o jsonpath='{.data.addresses}'

apiVersion: v1
kind: Service
metadata:
  name: web
  annotations:
    metallb.io/loadBalancerIPs: 2a01:4f8:fff0:18b:1000::1
spec:
  type: LoadBalancer
  ipFamilies: [IPv6]
  ipFamilyPolicy: SingleStack
  selector:
    app: web
  ports:
    - port: 80
      targetPort: 8080

spec.externalIPs and the deprecated spec.loadBalancerIP are both rejected on tenant Services and cannot be used instead. See kubectl mode.

kubectl apply is rejected

Admission policy rejects resources that break tenant guardrails. Common rejections include:

NodePort or ExternalName Services.
IPv4 or dual-stack LoadBalancer Services.
Host-network pods.
Node selectors.
Unapproved storage classes.
Edits to control-panel resources labelled dollarbox.io/managed-by=control-panel.

Adjust the manifest or use the control panel for control-panel-managed containers.

Quota is exhausted

Billing capacity and namespace quota are linked. To clear quota pressure:

Delete unused simple-mode containers.
Delete unused kubectl-created workloads.
Delete failed containers that still reserve capacity.
Increase subscribed dollarboxes from Billing.