Edition-Based Feature Gating#

Dify restricts or enables features based on which of three deployment editions is active: COMMUNITY (default self-hosted), ENTERPRISE (self-hosted with enterprise license), and CLOUD (hosted SaaS). The edition is a single StrEnum defined in api/enums/deployment_edition.py 1 and is the single source of truth for all gating decisions across the backend and frontend. It supersedes the now-removed ENTERPRISE_ENABLED and BILLING_ENABLED flags. 2

Edition Detection#

Backend#

DEPLOYMENT_EDITION is an environment variable read into DeploymentConfig in api/configs/deploy/__init__.py, with a default of DeploymentEdition.COMMUNITY. 3 All backend code imports dify_config.DEPLOYMENT_EDITION and compares it directly against DeploymentEdition enum members.

Frontend#

The backend exposes deployment_edition in the unauthenticated /system-features endpoint via FeatureService.get_system_features(). 2 The frontend fetches this at app startup via systemFeaturesQueryOptions() (a TanStack Query wrapper with staleTime: Infinity), caching the value for the full session. PR #39454 centralized this: the Root Layout now prefetches and hydrates system features server-side, eliminating ambiguous client-side environment checks. 4

There is also an EDITION → NEXT_PUBLIC_EDITION mapping applied by web/docker/entrypoint.sh, but consuming components use the system-features query path as the authoritative source. 5

Similarly, NEXT_PUBLIC_ENABLE_AGENT_V2 controls Agent V2 route availability entirely — feature-guard.ts calls notFound() if this env var is falsy 6, while web/features/agent-v2/feature-flag.ts exports isAgentV2Enabled() that reads it directly. 7 This is a deploy-time build flag, separate from the runtime edition check.

Backend API Guards#

Edition guards in api/controllers/console/wraps.py are applied as route decorators:

8

These are pure edition guards — distinct from the cloud_edition_billing_* family, which enforce subscription quota limits within CLOUD edition. 2

Additional inline checks against dify_config.DEPLOYMENT_EDITION appear outside decorators. For example, in tool_providers.py, the _resolve_identity_mode() helper coerces any non-OFF MCP identity-forwarding mode back to OFF unless DEPLOYMENT_EDITION == DeploymentEdition.ENTERPRISE — an enterprise-only capability enforced at the API layer. 9

Frontend UI Gating#

React components read deployment_edition from the cached system-features query and branch accordingly. The canonical pattern is:

const { data: deploymentEdition } = useSuspenseQuery({
  ...systemFeaturesQueryOptions(),
  select: (systemFeatures) => systemFeatures.deployment_edition,
})
const previewEnabled = deploymentEdition !== 'COMMUNITY'

Agent V2 Preview mode — gated in web/features/agent-v2/agent-detail/configure/page.tsx: 10

• previewEnabled is true for CLOUD and ENTERPRISE; false for COMMUNITY.
• ?mode=preview URL params are silently overridden to build on COMMUNITY.
• The Preview tab renders as a tooltip-wrapped disabled button when previewEnabled is false. 11
• ENTERPRISE always has preview enabled regardless of license validity status. 12

PR #39399 introduced the pattern of blocking preview mode on COMMUNITY edition. 13

Key Source Files#

Relationship to Other Gating Systems#

• Billing/quota checks (cloud_edition_billing_* decorators): enforce subscription plan limits within CLOUD edition only. Not edition gates by themselves.
• Enterprise branding (SystemFeatureModel.branding): gated separately on DEPLOYMENT_EDITION == ENTERPRISE inside get_system_features(). See the Branding Customization article.
• RBAC: controlled by its own permission decorators; RBAC is disabled by default in COMMUNITY edition and falls back to Owner/Admin-only checks.