Troubleshooting Components

Component Stuck in Provisioning

Component shows build.appstudio.openshift.io/request: configure-pac annotation but never completes provisioning.

Component spec.containerImage is not set, either by the developer or the Image Controller if it is deployed on your Konflux instance.

Check the component status:
```
kubectl get component <component-name> -o yaml | grep -A10 "annotations:"
```
Look for the build.appstudio.openshift.io/status annotation to see error details.
If your Konflux instance has the Image Controller deployed, check if the ImageRepository exists:
```
kubectl get imagerepository <imagerepository-name> -o yaml
```
If this object does exist, ensure that its labels and state are set with the following values:
```
metadata:
  labels:
    appstudio.redhat.com/application: <application-name>
    appstudio.redhat.com/component: <component-name>
status:
  state: ready
```
If ImageRepository was created via gitops (e.g. konflux-release-data repository), verify that its annotations are set with the following values (in the repository):
```
metadata:
  annotations:
    image-controller.appstudio.redhat.com/update-component-image: 'true'
```

Verify that .spec.containerImage is set on the Component:

kubectl get component <component-name> -o jsonpath='{.spec.containerImage}'

Set the Component ContainerImage

Set the container image for the Component if your Konflux instances do not have the Image Controller enabled:
```
kubectl patch component <component-name> --type=merge -p '{"spec":{"containerImage":"quay.io/your-org/your-repo"}}'
```
You must provide image registry credentials if you are manually setting the component’s container image. See Using different from default image repository.
Set the ImageRepository Annotations and Labels

If your Konflux cluster does have the Image Controller deployed, set the correct annotations and labels on Component’s associated ImageRepository object (in the case ImageRepository was created gitops (e.g. konflux-release-data repository) set those there):
```
metadata:
  annotations:
    image-controller.appstudio.redhat.com/update-component-image: 'true'
  labels:
    appstudio.redhat.com/application: <application-name>
    appstudio.redhat.com/component: <component-name>
```

You push code to your repository, but no PipelineRun is created.

Component not onboarded - Webhook not configured, GitHub App not installed, or PaC Repository CR missing
Invalid PipelineRun YAML - Broken YAML syntax or validation errors in PipelineRun definitions
Rate limits - Git provider API rate limits exceeded
Repository secret is wrong - Repository secret was removed or renamed after onboarding
Git token expired - Repository token in the secret expired

Check the component status to see if it was properly onboarded:
```
kubectl get component <component-name> -o yaml | grep -A10 "annotations:"
```
Look for the build.appstudio.openshift.io/status annotation to see error details.
Check if the Pipelines as Code Repository object exists:
```
kubectl get repository -n <namespace>
```
This command will return all Repository objects in your namespace. You will need to inspect individual records to identify the appropriate object and status.

Check repository secret in the Pipelines as Code Repository object:

kubectl get repository <repository-name> -o jsonpath='{.spec.git_provider.secret.name}'

And verify that secret exists and has correct credentials:

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

Verify PipelineRun` definitions exist in your source code repository:
```
ls .tekton/
```
You should see YAML files containing PipelineRun definitions. During onboarding, these are typically named <component-name>-on-push.yaml and <component-name>-on-pull-request.yaml, but any valid filename can be used.

Review Component Status:

The Component may not have completed the Repository object provisioning. Check component status for root causes and actions to take:
```
kubectl get component <component-name> -o yaml | grep "build.appstudio.openshift.io/status"
```
Re-onboard the Component:

Re-trigger the PipelineRun pull request by adding the configure-pac annotation to the Component:
```
kubectl annotate component <component-name> build.appstudio.openshift.io/request=configure-pac
```
Check Repository Credentials:

For repositories not using the GitHub App, ensure git credentials are configured and re-provision the component.

See Onboarding from GitLab or Onboarding from Forgejo for more information.

You try to delete a Component, but it remains in Terminating state.

Finalizers not removed - Component has finalizers that prevent deletion
Dependent resources exist - Resources owned by the Component still exist
Controller not running - Build Service controller is not processing the deletion
Repository secret doesn’t exist - Secret for repository doesn’t exist
Operator has big workqueue - Operator was just restarted and has workqueue which has to be processed first

Wait for Finalizers to Process

Wait for the Build Service controller to process the deletion. If the controller is not running, the finalizers won’t be removed automatically.
Report issue

Finalizer shouldn’t be manually removed as it will leave orphaned resources in your cluster, and proper cleanup won’t be performed.