#Hub Resolver Cannot Resolve a Resource

#Problem Description

A TaskRun or PipelineRun references a remote resource with resolver: hub, but Tekton cannot resolve the Task, Pipeline, or StepAction from artifacthub-shim.

#Error Manifestation

Common symptoms include:

• The run stays in a resolution failure state.
• No workload Pod is created.
• The run status or resolver logs mention a missing package or version.
• The resolver still tries to use the default upstream Artifact Hub endpoint.

Example hub reference:

taskRef:
  resolver: hub
  params:
    - name: type
      value: artifact
    - name: catalog
      value: catalog
    - name: kind
      value: task
    - name: name
      value: run-script
    - name: version
      value: "0.1.0"

#Root Cause Analysis

The usual causes are:

1. Hub resolver is not enabled.
2. TektonConfig does not set the hub resolver type to artifact.
3. The reconciled artifact-hub-api does not point to artifacthub-shim.
4. The resolver Pod has not picked up the updated ConfigMap.
5. The catalog, kind, name, or version parameter does not match a shim package.
6. The target repository source is invalid, degraded without a last-good shard, or disabled.

#Troubleshooting

#1. Verify TektonConfig

Check the hub resolver settings in TektonConfig:

kubectl get tektonconfig config -o yaml

The spec.pipeline section should include:

spec:
  pipeline:
    enable-hub-resolver: true
    hub-resolver-config:
      artifact-hub-api: http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local
      default-artifact-hub-task-catalog: catalog
      default-artifact-hub-pipeline-catalog: catalog-pipelines
      default-kind: task
      default-tekton-hub-catalog: catalog
      default-type: artifact

If default-type is not artifact, add type: artifact to each hub reference or update the default.

#2. Verify the reconciled resolver ConfigMap

The operator reconciles TektonConfig.spec.pipeline.hub-resolver-config into the hubresolver-config ConfigMap.

RESOLVER_NAMESPACE="$(kubectl get tektonconfig config \
  -o jsonpath='{.spec.targetNamespace}')"

kubectl get configmap hubresolver-config \
  -n "${RESOLVER_NAMESPACE}" \
  -o yaml

Expected values:

data:
  artifact-hub-api: http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local
  default-tekton-hub-catalog: catalog
  default-type: artifact

Also check the resolver feature flag:

kubectl get configmap resolvers-feature-flags \
  -n "${RESOLVER_NAMESPACE}" \
  -o jsonpath='{.data.enable-hub-resolver}{"\n"}'

Expected output:

true

#3. Check resolver Pod environment

Find the remote resolver Pod:

kubectl get pods -n "${RESOLVER_NAMESPACE}"

Check whether the resolver Deployment consumes hubresolver-config:

kubectl get deployment -n "${RESOLVER_NAMESPACE}" \
  -o yaml | grep -A5 -B5 ARTIFACT_HUB_API

If the ConfigMap is correct but the resolver still uses old values, restart the resolver Pod so it reads the updated environment variables:

kubectl delete pod -n "${RESOLVER_NAMESPACE}" \
  -l app.kubernetes.io/component=resolvers

If your installation uses different resolver labels, delete the specific remote resolver Pod returned by kubectl get pods.

#4. Verify shim Service and repository health

Check that the shim Deployment and Service are available:

kubectl get deployment,service,endpoints \
  -n artifacthub-shim-system \
  -l app.kubernetes.io/name=artifacthub-shim

Then inspect the repository ConfigMap Events for the catalog used by the hub reference:

kubectl describe configmap <repository-configmap-name> \
  -n artifacthub-shim-system

RepositorySourceReady means the catalog is visible to resolver clients. RepositorySourceInvalid or RepositorySourceDegraded means the resolver may fail even when the shim API pod itself is healthy.

#5. Verify the exact package requested by the resolver

Compare the hub resolver params with the repository source and catalog content:

• catalog must match repository.yaml.gitRepositories[].repositories[].name.
• kind must match the repository source kind.
• name must match the package directory name under the configured path.
• version must match a version directory or a supported semver-compatible selector.

For built-in catalog resources, use catalog for Tasks and catalog-pipelines for Pipelines. Historical Pipeline references that still use catalog are supported by a shim catalog alias, but new references should use catalog-pipelines.

For migrated custom Tekton Hub catalogs, the operator may create repositories such as team-a, team-a-pipelines, and team-a-stepactions, with a legacy alias such as team-a pointing to the Pipeline repository for Pipeline lookups. API responses and UI labels still return the canonical repository name. If the resolver fails after migration, check the repository ConfigMap for legacyCatalogAliases and verify that the requested kind matches the alias scope.

If the source is Ready but the package is still missing, check disabled package rules in the repository ConfigMap and chart values.

#6. Check version formatting

Quote numeric-looking versions in YAML:

- name: version
  value: "0.1.0"

artifacthub-shim supports normalized semver lookup. For example, a catalog directory named 0.1 can be returned as 0.1.0 for resolver compatibility. If the resolver uses a version constraint, verify that the catalog contains a matching non-prerelease version directory.

#7. Check resolver logs

kubectl logs -n "${RESOLVER_NAMESPACE}" \
  deployment/tekton-pipelines-remote-resolvers \
  --tail=200

If your resolver Deployment has a different name, use:

kubectl get deployment -n "${RESOLVER_NAMESPACE}"

Then query logs from the matching resolver Deployment or Pod.

#Related Content

• Quick Start
• Consume Resources with the Hub Resolver
• Configure Tekton Integration
• Historical Pipeline Catalog References
• Repository Source Is Not Visible
• Tekton Hub Resolver