Troubleshoot

Common issues and solutions for kup6s-pages.

Site Stuck in “Pending”

Check the syncer logs:

kubectl logs -n kup6s-pages -l app.kubernetes.io/component=syncer

Common causes:

• Git repository URL is incorrect

• Network issues reaching the Git server

• Authentication failed (for private repos)

Certificate Not Ready

Check cert-manager:

kubectl get certificate -n <namespace>
kubectl describe certificate <name> -n <namespace>

Check certificate request:

kubectl get certificaterequest -n <namespace>
kubectl describe certificaterequest <name> -n <namespace>

Common causes:

• DNS not pointing to cluster

• Rate limiting from Let’s Encrypt

• ClusterIssuer misconfigured

404 Errors

1. Verify the site directory exists:

kubectl exec -n kup6s-pages deploy/pages-syncer -- ls -la /sites/

2. Check if the repo was cloned successfully:

kubectl get staticsite <name> -n <namespace> -o yaml

3. If using path subpath, verify the symlink:

kubectl exec -n kup6s-pages deploy/pages-syncer -- ls -la /sites/<sitename>

Private Repo Authentication Fails

1. Verify the Secret exists and has the correct key:

kubectl get secret <name> -n <namespace>
kubectl get secret <name> -n <namespace> -o jsonpath='{.data.password}' | base64 -d

2. Test the token manually:

git clone https://git:<TOKEN>@forgejo.example.com/org/repo.git

Force Re-sync

Trigger a manual sync via webhook (if enabled):

curl -X POST https://webhook.pages.kup6s.com/sync/<namespace>/<sitename>

Or delete and recreate the StaticSite to force a fresh clone.

Check Operator Logs

kubectl logs -n kup6s-pages -l app.kubernetes.io/component=operator

Check nginx Logs

kubectl logs -n kup6s-pages -l app.kubernetes.io/component=nginx