What causes "failed to load declarative subscriptions: %s" in dapr/dapr?

Inspect the nested error to see which subscription and which field failed

failed to load declarative subscriptions: %s

Error message

failed to load declarative subscriptions: %s

What it means

loadDeclarativeSubscriptions failed: the subscription loader (disk path for standalone, operator client for Kubernetes) returned an error, or committing one of the subscriptions to the processor returned an error. Declarative subscriptions are read before StartAppSubscriptions so that first-declared-per-topic dedup works; any failure here aborts init.

Source

Thrown at pkg/runtime/runtime.go:758

		return fmt.Errorf("failed to load components: %s", err)
	}

	if err = a.flushOutstandingComponents(ctx); err != nil {
		return err
	}

	err = a.loadHTTPEndpoints(ctx)
	if err != nil {
		log.Warnf("failed to load HTTP endpoints: %s", err)
	}

	if err = a.flushOutstandingHTTPEndpoints(ctx); err != nil {
		return err
	}

	err = a.loadDeclarativeSubscriptions(ctx)
	if err != nil {
		return fmt.Errorf("failed to load declarative subscriptions: %s", err)
	}

	if err = a.channels.Refresh(); err != nil {
		log.Warnf("failed to open %s channel to app: %s", string(a.runtimeConfig.appConnectionConfig.Protocol), err)
	}

	// Setup allow/deny list for secrets
	a.populateSecretsConfiguration()

	a.namespace = security.CurrentNamespace()

	// Create and start the external gRPC server
	a.daprUniversal = universal.New(universal.Options{
		AppID:                       a.runtimeConfig.id,
		Namespace:                   a.namespace,
		Logger:                      logger.NewLogger("dapr.api"),
		CompStore:                   a.compStore,
		Resiliency:                  a.resiliency,

View on GitHub (pinned to 74ad417027)

Solutions

Inspect the nested error to see which subscription and which field failed
Fix each Subscription manifest: required fields are pubsubname, topic, route; validate scopes and apiVersion against the docs
Remove subscriptions you no longer use from the resources path/namespace
In k8s, confirm the operator is healthy and RBAC allows listing subscriptions

Example fix

# before
apiVersion: dapr.io/v1alpha1
kind: Subscription
metadata:
  name: orders-sub
spec:
  pubsubname: redis-pubsub
  topic: orders
# after
spec:
  pubsubname: redis-pubsub
  topic: orders
  route: /orders

Defensive patterns

Strategy: validation

Validate before calling

func validateSubscription(s subapi.Subscription) error {
    if s.Spec.PubsubName == "" || s.Spec.Topic == "" || s.Spec.Route == "" {
        return fmt.Errorf("subscription %s: pubsubname, topic, and route are required", s.Name)
    }
    return nil
}

Type guard

func isDeclarativeSubscription(obj runtime.Object) bool {
    _, ok := obj.(*subapi.Subscription)
    return ok
}

Prevention

Require pubsubname/topic/route in subscription manifest templates
Keep subscription files out of unrelated folders scanned by --resources-path
Validate Subscription resources with kubectl --dry-run=server to catch schema errors pre-deploy

When it happens

Trigger: A Subscription YAML in the resources path that fails schema validation: missing required pubsubname/topic/route, invalid scopes, bad apiVersion/kind; kubernetes mode with an operator stream error; or the pending-subscription processing loop returning an error for one resource.

Common situations: Hand-edited subscription files missing 'route'; mixing v1alpha1 and v2alpha1 apiVersions incorrectly; leftover test subscriptions in the components folder; operator/RBAC problems in-cluster.

Related errors

AI-assisted analysis of dapr/dapr@74ad417027 (2026-08-16). Data as JSON: /api/errors/7c8bf15c099f2c6d. Report an issue: GitHub.