Tekton TaskRun Troubleshooting: Debug Step Failures (2026)

A Tekton TaskRun is failing because a specific step within its steps array exited with a non-zero status code, indicating an error occurred during its execution.

Common Causes and Fixes

1. Container Image Not Found or Inaccessible:

   • Diagnosis: Check the kubectl logs <pod-name> -c <step-name> for an error like exec format error or failed to pull image. Also, examine the kubectl describe pod <pod-name> output for ImagePullBackOff or ErrImagePull events.
   • Fix: Ensure the image specified in the step configuration is correct and accessible from your Kubernetes cluster. If it’s a private registry, verify that imagePullSecrets are correctly configured in the Task or TaskRun’s service account. For example, if your image is my-private-registry.com/my-image:latest, and it requires authentication, your TaskRun might need:

     apiVersion: tekton.dev/v1beta1
     kind: TaskRun
     metadata:
       name: my-taskrun-with-private-image
     spec:
       serviceAccountName: tekton-sa # Ensure this SA has the 'imagePullSecrets' set
       taskRef:
         name: my-task
       params:
         # ...
     

     And the tekton-sa service account would have:

     apiVersion: v1
     kind: ServiceAccount
     metadata:
       name: tekton-sa
     imagePullSecrets:
     - name: my-registry-secret # This secret contains registry credentials
     

   • Why it works: Kubernetes cannot start a container if it can’t pull its image. Correcting the image name or providing valid credentials allows the container runtime to fetch and execute the image.

2. Command Not Found in Container:

   • Diagnosis: Inspect kubectl logs <pod-name> -c <step-name>. You’ll likely see an error like sh: 1: <command>: not found or bash: <command>: command not found.
   • Fix: The command you’re trying to execute in the script or command field of the step is not present in the container image’s PATH. Either install the command within the image (by building a custom image or using install scripts if the base image supports it) or specify the full path to the executable. For example, if git is not in PATH but located at /usr/local/bin/git:

     steps:
     - name: checkout
       image: alpine:latest
       script: |
         /usr/local/bin/git clone https://github.com/my/repo.git
     

   • Why it works: Explicitly providing the full path bypasses the need for the command to be discoverable in the system’s PATH environment variable.

3. Script Syntax Errors or Runtime Errors:

   • Diagnosis: Examine kubectl logs <pod-name> -c <step-name>. The output will show the exact error message from your script interpreter (e.g., bash, sh, python). This could be a typo, a missing semicolon, an undefined variable, or a logic error in your script.
   • Fix: Carefully review the script content for syntax errors, logical flaws, or runtime exceptions. Often, the error message is quite direct. For a bash script, ensure proper quoting, variable expansion, and correct command usage. For example, if you have echo $MY_VAR and MY_VAR is not set, it might cause issues depending on set -e or set -u.

     # Incorrect: variable not quoted, could fail if it contains spaces
     # script: echo Hello $MY_VAR
     
     # Corrected: variable quoted
     script: |
       MY_VAR="value with spaces"
       echo "Hello ${MY_VAR}"
     

   • Why it works: Correcting the script’s code or logic resolves the interpreter’s error, allowing the script to execute successfully.

4. Missing or Incorrect Arguments/Parameters:

   • Diagnosis: Check kubectl logs <pod-name> -c <step-name>. The error might be related to a program expecting arguments that weren’t provided, or receiving them in the wrong format. For example, a command like kubectl apply -f might fail if the -f argument is missing or points to a non-existent file.
   • Fix: Verify that all required parameters defined in the Task are being passed correctly to the TaskRun, and that these parameters are then used correctly within the step’s script or command. Ensure that any args provided to the step are correctly formatted. If a parameter value is supposed to be a file path, ensure it’s correctly mounted as a volume if necessary.

     # Task definition
     apiVersion: tekton.dev/v1beta1
     kind: Task
     metadata:
       name: my-deploy-task
     spec:
       params:
         - name: manifest-path
           type: string
       steps:
         - name: deploy
           image: bitnami/kubectl:latest
           script: |
             kubectl apply -f $(params.manifest-path)
     

     # TaskRun passing the parameter
     apiVersion: tekton.dev/v1beta1
     kind: TaskRun
     metadata:
       name: deploy-taskrun
     spec:
       taskRef:
         name: my-deploy-task
       params:
         - name: manifest-path
           value: "/workspace/source/manifests/deployment.yaml" # Correct path
     

   • Why it works: Providing the expected arguments and parameters to the command or script ensures it has the necessary information to operate correctly.

5. File System Permissions or Missing Files:

   • Diagnosis: Look for Permission denied errors in kubectl logs <pod-name> -c <step-name>, or errors indicating a file or directory doesn’t exist. This often happens when a step tries to write to a volume that’s mounted read-only, or tries to execute a file without execute permissions.
   • Fix: Ensure that any volumes used by the step have the correct permissions. If a step needs to write to a volume, it might need to be mounted with readWriteMany access if shared across nodes, or the volume itself needs to have appropriate permissions set. For files that need to be executed, ensure they have +x permissions. You might need to chmod +x a script before executing it.

     steps:
     - name: setup-script
       image: alpine:latest
       script: |
         # Create a directory and ensure it's writable
         mkdir -p /workspace/shared/output
         chmod 777 /workspace/shared/output
     
         # If a script needs execution, ensure it has the flag
         echo '#!/bin/sh\necho "Hello"' > /workspace/shared/my_script.sh
         chmod +x /workspace/shared/my_script.sh
         /workspace/shared/my_script.sh
     

   • Why it works: Correct file system permissions allow the container process to perform the necessary read, write, or execute operations on files and directories.

6. Resource Constraints (CPU/Memory):

   • Diagnosis: The pod might be OOMKilled (Out Of Memory Killed). Check kubectl get events for events related to the pod, or kubectl describe pod <pod-name> for Reason: OOMKilled in the container status. Logs might be sparse if the container is killed abruptly.
   • Fix: Increase the resource requests and limits for the container in your Task definition or override them in the TaskRun.

     steps:
     - name: resource-intensive-step
       image: ubuntu:latest
       resources:
         requests:
           cpu: "500m"
           memory: "512Mi"
         limits:
           cpu: "1"
           memory: "1Gi"
       script: |
         # Some memory-hungry operation
         sleep 60
     

   • Why it works: Providing sufficient CPU and memory resources prevents the Kubernetes node from terminating the container due to resource starvation.

After fixing these, the next error you’ll likely encounter is a PipelineRun failing because the TaskRun it depends on successfully completed, but the PipelineRun itself has a condition that is not met, or another TaskRun within the pipeline has failed.