🚨 Crossplane Error Guide: 'ProviderConfig not found' — Create the Missing ProviderConfig

Overview

Every Crossplane managed resource references a ProviderConfig that tells the provider which credentials and settings to use. If the referenced ProviderConfig does not exist (or is the wrong API group), the managed resource never becomes ready and its status carries:

cannot resolve references: cannot get referenced ProviderConfig: ProviderConfig.aws.upbound.io "default" not found

You will see it in the resource’s status.conditions as a Synced: False reason ReconcileError. Until a matching ProviderConfig exists, the provider cannot authenticate and creates nothing.

Symptoms

• kubectl get managed shows the resource SYNCED=False, READY=False.
• kubectl describe events include cannot get referenced ProviderConfig ... not found.
• The resource sits indefinitely with no corresponding cloud resource created.
• It appears right after installing a provider, or after switching from the community provider to the Upbound family provider (different API group).

Common Root Causes

• No ProviderConfig created — the provider is installed and healthy, but no ProviderConfig object exists.
• Name mismatch — the resource’s spec.providerConfigRef.name does not match any ProviderConfig’s name (default is default).
• Wrong API group — the resource is from aws.upbound.io but you created a ProviderConfig in aws.crossplane.io (or vice versa); each provider family has its own ProviderConfig kind.
• Provider not yet healthy — the ProviderConfig CRD is not installed because the provider is still installing.
• Namespace/scope confusion — expecting a namespaced object where ProviderConfig is cluster-scoped.

Diagnostic Workflow

Check the managed resource’s conditions for the exact reference it wants:

kubectl get managed
kubectl describe <resource-kind> <name> | sed -n '/Conditions/,/Events/p'

List existing ProviderConfigs across every provider API group:

kubectl get providerconfigs.aws.upbound.io
kubectl get providerconfig -A --all-namespaces 2>/dev/null
kubectl api-resources | grep -i providerconfig

Confirm the provider is installed and healthy (the ProviderConfig CRD comes from it):

kubectl get providers.pkg.crossplane.io
kubectl get crds | grep -i providerconfig

Check what the resource references:

kubectl get <resource-kind> <name> -o jsonpath='{.spec.providerConfigRef.name}{"\n"}'

Example Root Cause Analysis

A platform team migrated from the community provider-aws (aws.crossplane.io) to the Upbound family provider-family-aws (aws.upbound.io). They kept their existing ProviderConfig manifest, which declared apiVersion: aws.crossplane.io/v1beta1. New S3 Bucket resources from s3.aws.upbound.io reported cannot get referenced ProviderConfig: ProviderConfig.aws.upbound.io "default" not found.

The provider was healthy and a ProviderConfig existed — but in the wrong API group. Upbound managed resources look for a ProviderConfig in aws.upbound.io, and the only one present was in aws.crossplane.io. kubectl get providerconfigs.aws.upbound.io returned nothing, confirming it. The fix was to create a ProviderConfig with apiVersion: aws.upbound.io/v1beta1, named default, referencing the same credentials Secret. Once applied, the buckets resolved their reference, went SYNCED=True, and provisioned. The stale aws.crossplane.io ProviderConfig was then removed.

Prevention Best Practices

• Create a ProviderConfig immediately after installing a provider, before applying any managed resources.
• Match the ProviderConfig API group to the exact provider family your resources come from (aws.upbound.io vs aws.crossplane.io).
• Keep the ProviderConfig name aligned with providerConfigRef.name (default default), and set it explicitly in resources when using multiple configs.
• Gate resource creation on provider health in GitOps (sync waves / dependsOn) so ProviderConfig CRDs exist first.
• When migrating provider families, recreate ProviderConfigs in the new API group before switching resources.

Quick Command Reference

kubectl get managed                                   # SYNCED/READY per resource
kubectl get providerconfigs.aws.upbound.io            # list configs (right group)
kubectl api-resources | grep -i providerconfig        # which config kinds exist
kubectl get providers.pkg.crossplane.io               # provider health
kubectl describe bucket <name>                         # see the reference error

Conclusion

ProviderConfig not found means a managed resource points at a ProviderConfig that does not exist in the expected API group. Confirm the provider is healthy, list ProviderConfigs in the exact group your resources use, and create one (right name, right apiVersion, wired to your credential Secret). Aligning API groups is the usual fix after a provider-family migration, and creating ProviderConfigs before resources prevents the error entirely.