By name: debugging-task-failures description: Use when a Tekton task test fails in CI or locally and you need to find the root cause
Debugging Task Failures
Overview
Task tests run as Tekton PipelineRuns in isolated namespaces. Debugging requires inspecting the PipelineRun, TaskRun, and pod logs in the test namespace.
Namespace Convention
The test runner creates namespace {task-name}-{version-with-hyphens}. Example: task yaml-lint version 0.1 runs in namespace yaml-lint-0-1.
Debugging Steps
1. Find the failed run
NS="<task-name>-<version-hyphens>"
kubectl get pipelinerun -n "$NS"
kubectl get taskrun -n "$NS"
2. Read the logs
# All logs for a pipelinerun
tkn pr logs <pipelinerun-name> -n "$NS"
# Specific taskrun
tkn tr logs <taskrun-name> -n "$NS"
# Raw pod logs (if tkn output is truncated)
kubectl logs -n "$NS" -l tekton.dev/pipelineRun=<pipelinerun-name> --all-containers
3. Check events
kubectl get events -n "$NS" --sort-by=.lastTimestamp
4. Inspect task YAML as applied
kubectl get task <task-name> -n "$NS" -o yaml
5. Check pre-apply hook output
If a pre-apply-task-hook.sh exists, verify its resources were created:
kubectl get all -n "$NS"
kubectl get pvc,configmap,secret -n "$NS"
Common Failure Patterns
| Symptom | Likely Cause |
|---|---|
ImagePullBackOff |
Image digest wrong or registry auth missing |
| Task passes but negative test reports success | test/assert-task-failure annotation value doesn't match pipeline task name |
No such file or directory in script |
PVC data path mismatch between setup and task steps |
Pipeline stuck in Unknown |
Cluster resource limits or Tekton controller not ready |
Permission denied |
Missing RBAC — add RoleBinding in pre-apply hook |
CI vs Local Differences
- CI uses a fresh kind cluster per run; local clusters may have leftover state
- CI filters by changed files — only tasks with modified
tasks/**/*.{yaml,sh}are tested - Namespace from a previous local run may still exist; delete it or the runner reuses it