Fix Tekton Pipeline Run Failed

What's Actually Happening

Tekton PipelineRun fails to complete. Pipeline execution stops with errors or tasks fail during execution.

The Error You'll See

```bash $ kubectl get pipelinerun -n tekton-pipelines

NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME my-pipeline-run False TaskFailed 2m 1m

$ kubectl describe pipelinerun my-pipeline-run -n tekton-pipelines

Error: taskrun my-pipeline-run-task-1 has failed ```

Task error:

Error: step step-name exited with non-zero exit code: 1

Workspace error:

Error: workspace binding not found: source

Parameter error:

Error: missing parameter: required-param

Why This Happens

1. 1.Task execution error - Step command fails
2. 2.Workspace not bound - Required workspace not provided
3. 3.Parameter missing - Required parameter not passed
4. 4.Resource not found - Referenced task or cluster task missing
5. 5.Timeout exceeded - Pipeline takes too long
6. 6.Image pull error - Task image cannot be pulled

Step 1: Check PipelineRun Status

```bash # List PipelineRuns: kubectl get pipelinerun -A

# Get specific PipelineRun: kubectl get pipelinerun my-pipeline-run -n default -o yaml

# Describe PipelineRun: kubectl describe pipelinerun my-pipeline-run -n default

# Check conditions: kubectl get pipelinerun my-pipeline-run -n default -o jsonpath='{.status.conditions}'

# Check task runs: kubectl get taskrun -n default -l tekton.dev/pipelineRun=my-pipeline-run

# View PipelineRun events: kubectl get events -n default --field-selector involvedObject.name=my-pipeline-run

# Check specific TaskRun: kubectl describe taskrun my-pipeline-run-task-1 -n default

# Check TaskRun logs: tkn taskrun logs my-pipeline-run-task-1 -n default ```

Step 2: Check TaskRun Status

```bash # List TaskRuns: kubectl get taskrun -n default

# Get TaskRun details: kubectl get taskrun my-pipeline-run-task-1 -n default -o yaml

# Describe TaskRun: kubectl describe taskrun my-pipeline-run-task-1 -n default

# Check step status: kubectl get taskrun my-pipeline-run-task-1 -n default -o jsonpath='{.status.steps}'

# Check pod status: kubectl get pod -n default -l tekton.dev/taskRun=my-pipeline-run-task-1

# View TaskRun logs: tkn taskrun logs my-pipeline-run-task-1 -n default

# Or via kubectl: kubectl logs -n default -l tekton.dev/taskRun=my-pipeline-run-task-1 --all-containers

# Check step details: kubectl get taskrun my-pipeline-run-task-1 -n default -o yaml | grep -A10 "steps:"

# Check sidecar status: kubectl get taskrun my-pipeline-run-task-1 -n default -o jsonpath='{.status.sidecars}' ```

Step 3: View Step Logs

```bash # Get TaskRun pod: POD=$(kubectl get pod -n default -l tekton.dev/taskRun=my-pipeline-run-task-1 -o jsonpath='{.items[0].metadata.name}')

# List containers in pod: kubectl get pod $POD -n default -o jsonpath='{.spec.containers[*].name}'

# View specific step logs: kubectl logs $POD -n default -c step-name

# View all containers: kubectl logs $POD -n default --all-containers

# Stream logs: kubectl logs $POD -n default -f --all-containers

# Previous container (if restarted): kubectl logs $POD -n default -c step-name --previous

# Check init container logs: kubectl logs $POD -n default -c prepare

# Check entrypoint logs: kubectl logs $POD -n default -c place-scripts ```

Step 4: Check Workspace Bindings

```bash # Check Pipeline workspace bindings: kubectl get pipelinerun my-pipeline-run -n default -o yaml | grep -A10 "workspaces:"

# Check Task workspace requirements: kubectl get task my-task -n default -o yaml | grep -A10 "workspaces:"

# Common workspace types: # - PersistentVolumeClaim # - VolumeClaimTemplate # - EmptyDir # - ConfigMap # - Secret

# Create PVC for workspace: kubectl apply -f - <<EOF apiVersion: v1 kind: PersistentVolumeClaim metadata: name: workspace-pvc spec: accessModes: - ReadWriteOnce resources: requests: storage: 1Gi EOF

# Bind workspace in PipelineRun: apiVersion: tekton.dev/v1 kind: PipelineRun metadata: name: my-pipeline-run spec: pipelineRef: name: my-pipeline workspaces: - name: source persistentVolumeClaim: claimName: workspace-pvc

# Use VolumeClaimTemplate: workspaces: - name: source volumeClaimTemplate: spec: accessModes: - ReadWriteOnce resources: requests: storage: 1Gi ```

Step 5: Check Parameters

```bash # Check Pipeline parameters: kubectl get pipeline my-pipeline -n default -o yaml | grep -A10 "params:"

# Check PipelineRun parameters: kubectl get pipelinerun my-pipeline-run -n default -o yaml | grep -A10 "params:"

# Required parameters must be provided: # Pipeline definition: params: - name: image-tag type: string description: The image tag

# PipelineRun must provide: params: - name: image-tag value: "v1.0.0"

# Default values: params: - name: image-tag type: string default: "latest"

# Check parameter substitution in tasks: kubectl get task my-task -n default -o yaml | grep '\$\(params'

# Verify param syntax: # Correct: $(params.image-tag) # Wrong: ${params.image-tag} or $params.image-tag ```

Step 6: Check Task Definition

```bash # List Tasks: kubectl get task -A

# List ClusterTasks: kubectl get clustertask

# Get Task definition: kubectl get task my-task -n default -o yaml

# Check TaskRef in Pipeline: kubectl get pipeline my-pipeline -n default -o yaml | grep -A5 "taskRef"

# Verify task exists: kubectl get task my-task -n default

# For ClusterTask, verify reference: # taskRef: # name: my-clustertask # kind: ClusterTask

# Check step script: kubectl get task my-task -n default -o yaml | grep -A10 "script:"

# Check step command: kubectl get task my-task -n default -o yaml | grep -A5 "command:"

# Verify image exists: docker pull gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/bash:v0.30.0 ```

Step 7: Fix Image Pull Errors

```bash # Check image in task: kubectl get task my-task -n default -o jsonpath='{.spec.steps[0].image}'

# Test image pull: docker pull <image-name>

# For private registry, create secret: kubectl create secret docker-registry regcred \ --docker-server=myregistry.com \ --docker-username=user \ --docker-password=pass \ -n default

# Add to PipelineRun: apiVersion: tekton.dev/v1 kind: PipelineRun metadata: name: my-pipeline-run spec: pipelineRef: name: my-pipeline taskRunSpecs: - pipelineTaskName: task-name computeResources: requests: memory: 1Gi podTemplate: imagePullSecrets: - name: regcred

# Or add to Task: spec: steps: - name: step-name image: myregistry.com/myimage:latest sidecars: - name: sidecar image: myregistry.com/sidecar:latest ```

Step 8: Check Timeout Settings

```bash # Check PipelineRun timeout: kubectl get pipelinerun my-pipeline-run -n default -o jsonpath='{.spec.timeouts}'

# Default timeout is 1 hour: # timeouts: # pipeline: 1h # tasks: 0h30m0s # finally: 0h30m0s

# Increase timeout: apiVersion: tekton.dev/v1 kind: PipelineRun metadata: name: my-pipeline-run spec: pipelineRef: name: my-pipeline timeouts: pipeline: 2h tasks: 1h

# Disable timeout: timeouts: pipeline: "0"

# Check TaskRun timeout: kubectl get taskrun my-task-run -n default -o jsonpath='{.spec.timeout}'

# Set task-level timeout: apiVersion: tekton.dev/v1 kind: Task metadata: name: my-task spec: steps: - name: long-running image: alpine timeout: 30m script: | #!/bin/sh sleep 1800 ```

Step 9: Check Tekton Controller

```bash # Check Tekton pods: kubectl get pods -n tekton-pipelines

# Check controller logs: kubectl logs -n tekton-pipelines deploy/tekton-pipelines-controller

# Check webhook logs: kubectl logs -n tekton-pipelines deploy/tekton-pipelines-webhook

# Check recent events: kubectl get events -n tekton-pipelines --sort-by='.lastTimestamp'

# Check controller resources: kubectl top pods -n tekton-pipelines

# Check Tekton version: kubectl get deploy -n tekton-pipelines -o jsonpath='{.items[0].spec.template.spec.containers[0].image}'

# Restart controller: kubectl rollout restart deploy/tekton-pipelines-controller -n tekton-pipelines

# Check RBAC: kubectl get sa -n tekton-pipelines kubectl get clusterrole | grep tekton ```

Step 10: Tekton Verification Script

```bash # Create verification script: cat << 'EOF' > /usr/local/bin/check-tekton-pipeline.sh #!/bin/bash

RUN=${1:-"my-pipeline-run"} NS=${2:-"default"}

echo "=== PipelineRun Status ===" kubectl get pipelinerun $RUN -n $NS

echo "" echo "=== PipelineRun Conditions ===" kubectl get pipelinerun $RUN -n $NS -o jsonpath='{.status.conditions}' | jq .

echo "" echo "=== TaskRuns ===" kubectl get taskrun -n $NS -l tekton.dev/pipelineRun=$RUN

echo "" echo "=== Failed TaskRuns ===" kubectl get taskrun -n $NS -l tekton.dev/pipelineRun=$RUN --field-selector status.conditions[?(@.type=="Succeeded")].status=false

echo "" echo "=== TaskRun Details ===" for tr in $(kubectl get taskrun -n $NS -l tekton.dev/pipelineRun=$RUN -o name); do echo "--- $tr ---" kubectl get $tr -n $NS -o jsonpath='{.status.conditions[0].message}' echo "" done

echo "" echo "=== Workspaces ===" kubectl get pipelinerun $RUN -n $NS -o yaml | grep -A10 "workspaces:"

echo "" echo "=== Parameters ===" kubectl get pipelinerun $RUN -n $NS -o yaml | grep -A10 "params:"

echo "" echo "=== Tekton Controller Logs ===" kubectl logs -n tekton-pipelines deploy/tekton-pipelines-controller --tail=10 | grep -i "$RUN"

echo "" echo "=== Recommendations ===" echo "1. Check TaskRun logs for step failures" echo "2. Verify all workspaces are bound" echo "3. Ensure required parameters are provided" echo "4. Check Task or ClusterTask exists" echo "5. Verify image can be pulled" echo "6. Review timeout settings" echo "7. Check RBAC permissions" EOF

chmod +x /usr/local/bin/check-tekton-pipeline.sh

# Usage: /usr/local/bin/check-tekton-pipeline.sh my-pipeline-run default ```

Tekton PipelineRun Checklist

Verify the Fix

```bash # After fixing Tekton PipelineRun issues

# 1. Create PipelineRun kubectl create -f pipelinerun.yaml // PipelineRun created

# 2. Check status kubectl get pipelinerun my-pipeline-run -n default -w // SUCCEEDED: True

# 3. View TaskRuns kubectl get taskrun -l tekton.dev/pipelineRun=my-pipeline-run // All SUCCEEDED: True

# 4. Check logs tkn pipelinerun logs my-pipeline-run -n default // All steps complete

# 5. Verify workspaces kubectl get pvc // PVCs bound

# 6. Check Tekton dashboard // PipelineRun shows green ```

Related Issues

• [Fix Jenkins Build Stuck](/articles/fix-jenkins-build-stuck)
• [Fix GitLab CI Pipeline Stuck](/articles/fix-gitlab-ci-pipeline-stuck)
• [Fix GitHub Actions Workflow Failed](/articles/fix-github-actions-workflow-failed)