Appendix D: Troubleshooting

This appendix is the single place for known issues when you run Appendix B: Installing TSF (installer, tsf, tsf deploy) and when you work through Module 2: Getting started with Konflux (pipelines, webhooks, registry pushes from builds).

Installation and tsf deploy

Scenarios that surface while you are inside the installer container running tsf—for example after Appendix B exercises.

Issue: Quay token error during deployment

Problem: The tsf deploy command fails with "token field not found in secret"

Solution:

  1. Verify your Quay token is valid by logging in to Quay.

  2. Delete the secret:

    oc delete secret tsf-quay-integration -n tsf

  3. Re-run the Quay integration command:

    tsf integration quay \
  --organization="$QUAY__ORG" \
  --token="$QUAY__API_TOKEN" \
  --url="$QUAY__URL" \
  --verbose

  4. Re-run the deployment:

    tsf deploy

Issue: tsf deploy runs a long time or prints little output

Problem: The deploy command runs without output for several minutes, or you are unsure whether it has stalled

Likely causes: Normal Helm processing and large image pulls (for example Keycloak, Red Hat Trusted Profile Analyzer)

Solution:

  1. This is often expected—Helm chart deployment can take time.

  2. Monitor progress separately:

    oc get pods -A --watch

  3. Typical completion time is about 15 minutes.

Konflux pipelines and onboarding

These tips match the hands-on modules: slow or stuck pipeline runs, push failures from a build, and missing webhooks.

Issue: Pipeline run is slow or appears stuck

Problem: Builds sit In Progress for many minutes after merging the onboarding pull request

Likely causes: Cold cache, registry pulls, vulnerability scans, signing steps

Ideas:

  1. Open the PipelineRun logs in Konflux so you see which TaskRun is executing

  2. Allow roughly 10–15 minutes for a first pipeline on a warmed cluster—longer on smaller clusters or first-time image pulls

  3. Start from the Konflux UI before escalating to oc; what you may inspect on the cluster depends on your RBAC

Issue: Konflux pipeline cannot push the image to Quay

Problem: Build pipeline succeeds but pushing the image to Quay fails

Likely causes: Wrong organization or repository, insufficient permissions for pushes, registry quota limits, or stale credentials on the cluster side your workspace relies on.

Ideas:

  1. Confirm the Quay organization and repository your component targets actually exist under the lab’s registry hostname

  2. If you administer the tenant, reconcile registry credentials against your cluster or operator documentation (TSF, Konflux, or your organization’s runbook)—otherwise ask your platform team to verify workspace-level registry integration

Issue: Component not triggering builds

Problem: Merged PR but pipeline never runs

Root cause: Webhook not configured or not reaching cluster

Solution:

  1. Check webhook configuration in GitHub/GitLab

  2. Verify cluster is publicly accessible

  3. Check Tekton EventListener:

    oc get eventlistener -A

  4. Check recent webhook deliveries in GitHub/GitLab settings