Tekton "persistentvolumeclaim X not found" for a workspace in CI

By Daniel Zoghalchali·Latchkey

A workspace binds a PersistentVolumeClaim by name, and either that PVC does not exist in the namespace, or it exists but stays Pending because no StorageClass can bind it. The pod cannot start.

What this error means

A TaskRun pod is Pending; describe shows "persistentvolumeclaim \"source-pvc\" not found" or the PVC is stuck Pending with "waiting for a volume to be created".

Warning  FailedScheduling  persistentvolumeclaim "source-pvc" not found

Common causes

The named PVC does not exist

The workspace binding references a claimName that was never created in the run namespace.

The PVC exists but cannot bind

No default StorageClass, or one that cannot provision, leaves the PVC Pending so the pod never schedules.

How to fix it

Create the PVC or use a volumeClaimTemplate

Prefer a volumeClaimTemplate so Tekton creates a fresh PVC per run and cleans it up.

spec:
  workspaces:
    - name: source
      volumeClaimTemplate:
        spec:
          accessModes: [ReadWriteOnce]
          storageClassName: standard
          resources:
            requests:
              storage: 1Gi

Fix the StorageClass so the PVC binds

1. Check PVC status with kubectl get pvc -n <ns>.
2. Ensure a default StorageClass exists, or set storageClassName explicitly.
3. Re-run once the PVC reaches Bound.

kubectl get pvc -n ci
kubectl get storageclass

How to prevent it

• Use volumeClaimTemplate for per-run storage instead of pre-created PVCs.
• Ensure the cluster has a working default StorageClass for CI.
• Name PVCs consistently if you bind them by claimName.

Frequently asked questions

Related guides

References

• Kubernetes documentation
• GitHub Actions documentation