Plugin Marketplace Connectivity#

Dify's plugin system requires outbound HTTPS access to marketplace.dify.ai for browsing, downloading, and installing plugins. In firewalled, air-gapped, or proxy-intercepting environments this connection fails, producing errors ranging from DNS resolution failures to MaxRetriesExceededError. The marketplace is optional — core Dify functionality is unaffected when it is unreachable, but no marketplace-sourced plugins can be installed or updated without it.

Edition Differences: Detail Pages#

COMMUNITY and ENTERPRISE editions open plugin and template detail pages on the official Marketplace (marketplace.dify.ai) in a new browser tab. CLOUD edition continues to display details in-app within modal dialogs.

For COMMUNITY and ENTERPRISE users, this means two types of connectivity are required:

1. Backend connectivity (server → marketplace.dify.ai): The Dify API container needs outbound HTTPS to browse, search, and install plugins.
2. Browser connectivity (user's browser → marketplace.dify.ai): The user's browser must also reach the Marketplace site to view detail pages.

If backend connectivity works but the browser cannot reach marketplace.dify.ai, users will be able to browse the marketplace and install plugins, but clicking a plugin or template card to view details will fail. Browser-level blocks are typically caused by corporate firewalls, DNS filtering, or proxy policies that differ from server-side network rules.

Architecture#

Plugin installation flows through two layers:

1. api/core/helper/marketplace.py — orchestrates calls to marketplace.dify.ai. Key functions: 1

   • download_plugin_pkg() — fetches the .difypkg binary via api/v1/plugins/download-url
   • batch_fetch_plugin_manifests() — POSTs to api/v1/plugins/batch to resolve plugin metadata
   • fetch_global_plugin_manifest() — GETs api/v1/dist/plugins/manifest.json and caches results in Redis

   All calls use a hard-coded 30-second timeout (MARKETPLACE_TIMEOUT = 30) and raw httpx (no SSRF proxy). 2

2. api/core/helper/download.py — download_with_size_limit() delegates the actual byte-fetch to remote_fetcher.make_request(), raising ValueError on 404 or size violations. 3

The marketplace base URL is controlled by two env vars in MarketplaceConfig 4:

Error Types and Where They Surface#

MaxRetriesExceededError and marketplace downloads: Calls in marketplace.py use raw httpx — not the SSRF proxy — so MaxRetriesExceededError is not raised on marketplace download failures. That error comes from ssrf_proxy.make_request() when other outbound requests (HTTP Request nodes, tool calls) exhaust their Squid-based retry budget. DNS/connection failures from the marketplace propagate as httpx.ConnectError and are swallowed by broad except Exception handlers in plugin_migration.py, which log the failure and mark the plugin as not-found. 7

Diagnosing Connectivity#

Verify reachability from inside the api container:

docker compose exec api curl -v https://marketplace.dify.ai

Common failure signatures in api container logs:

• WARNING ... fetch_latest_plugin_version ... [Errno -3] Temporary failure in name resolution — DNS blocked 8
• ERROR ... failed to fetch latest plugin version followed by an httpx.ConnectError stack trace — network-level block
• TCP_DENIED/403 in ssrf_proxy container output — Squid ACL blocking the request

For COMMUNITY and ENTERPRISE editions: If users can browse the marketplace but cannot view detail pages (clicking a card does nothing or opens a blank tab), the issue is likely browser-side connectivity. Test by opening https://marketplace.dify.ai directly in the user's browser. If that fails, check DNS, firewalls, or proxy settings on the client machine — not the Dify server.

Workarounds for Restricted Environments#

1. Disable the marketplace entirely

Set MARKETPLACE_ENABLED=false in .env to prevent the API from attempting marketplace calls at startup or during plugin sync. Plugins already installed will continue to work.

2. Corporate proxy / Zscaler / SSL inspection

If the connection fails with a TLS certificate error (Zscaler acts as a MITM proxy), inject your company's root CA into the api, web, and plugin_daemon containers. Alternatively set HTTP_PROXY / HTTPS_PROXY on those services in docker-compose.yaml so the container routes through the corporate proxy. 9

3. Manual .difypkg install (air-gapped)

Download .difypkg files from the Dify Marketplace web UI, transfer them to the isolated host, and upload via Plugins → Upload Plugin in the Dify console. No marketplace connectivity is required for this path. 8

4. Plugin packages with embedded uv.lock (air-gapped edge case)

Plugins v0.0.53+ of openai-api-compatible ship a uv.lock that hardcodes files.pythonhosted.org URLs, bypassing any private PyPI proxy. Community-tested workaround 10:

1. Set ENFORCE_LANGGENIUS_PLUGIN_SIGNATURES=false and FORCE_VERIFYING_SIGNATURE=false in the plugin_daemon env.
2. Strip the lock file: zip -d plugin.difypkg uv.lock
3. Upload the modified package; then exec into the plugin_daemon container and run uv sync inside the unpacked plugin directory, pointing at your internal PyPI proxy.

A proper fix (bundling complete offline packages) is tracked in issue #41849. 11

A community repackaging tool is also available: dify-plugin-repackaging. 11

Key Files#