Plugin System Timeouts#

Dify's plugin system has four distinct timeout layers that stack on top of each other. A slow LLM call will traverse all of them. Understanding each layer is necessary when tuning or debugging timeout errors.

Dify API worker
  │
  ├─[1] PLUGIN_DAEMON_TIMEOUT (API → Daemon HTTP)
  │ default 600 s
  │
  └─► Plugin Daemon (Go process)
        │
        ├─[2] PLUGIN_MAX_EXECUTION_TIMEOUT (Daemon execution limit)
        │ default 600 s
        │
        └─► Plugin Python process
              │
              ├─[3] OpenAI SDK / httpx Timeout (Daemon → LLM service)
              │ 315 s total, 300 s read, 10 s write, 5 s connect
              │
              └─[4] requests.post timeout (text_embedding / rerank)
                      60 s

Layer 1 — API-to-Daemon HTTP Timeout (PLUGIN_DAEMON_TIMEOUT)#

All plugin invocations from the Dify API go through BasePluginClient in api/core/plugin/impl/base.py, which makes synchronous blocking httpx calls to the plugin daemon. Both _request() and _stream_request() obtain the timeout value by calling _get_plugin_daemon_request_timeout(), which returns either a request-scoped override (if set) or the global plugin_daemon_request_timeout.

The global timeout is resolved at module import time from PLUGIN_DAEMON_TIMEOUT:

Configured in PluginConfig (api/configs/feature/__init__.py). Set to None to disable the timeout entirely.

Request-scoped overrides: Use the use_plugin_daemon_request_timeout(timeout_seconds) context manager to temporarily apply a shorter timeout for specific code paths without changing the global default. For example, suggested question generation wraps its LLM call with use_plugin_daemon_request_timeout(30.0) to prevent reasoning models from causing excessive latency — the 30-second override applies only to that invocation, and the global 600-second default remains in effect for all other plugin requests.

Worker impact: Both _request() and _stream_request() block the Gunicorn worker thread for the entire duration — including all upstream LLM inference time. Keep this value in mind when sizing SERVER_WORKER_AMOUNT.

Layer 2 — Daemon Execution Timeout (PLUGIN_MAX_EXECUTION_TIMEOUT)#

The plugin daemon (a separate Go binary) enforces its own per-invocation time cap via the environment variable PLUGIN_MAX_EXECUTION_TIMEOUT. This is a daemon-side setting, not present in the Dify API's Python config. In integration tests it is set to 600 seconds 4.

This timeout fires inside the daemon before the API-side PLUGIN_DAEMON_TIMEOUT would, when the plugin execution itself exceeds the limit. Both values default to 600 s, so they are effectively equivalent in the default configuration; lower PLUGIN_MAX_EXECUTION_TIMEOUT in the daemon if you want the daemon to abort plugin execution faster than the API-side HTTP timeout.

Layer 3 — OpenAI SDK HTTP Client Timeout (LLM Plugins)#

When a plugin calls an OpenAI-compatible LLM, the Python plugin process uses the openai SDK. The _CommonOpenAI._to_credential_kwargs() method in models/openai_api_compatible/models/common_openai.py hard-codes the following timeout for all requests made via the OpenAI Python client:

# common_openai.py line 26
"timeout": Timeout(315.0, read=300.0, write=10.0, connect=5.0)

5

These values are not configurable via environment variables — they are baked into the plugin source. The validation path in the OpenAILargeLanguageModel subclass uses a separate shorter timeout: _VALIDATE_TIMEOUT = (10, 300) — a (connect, read) tuple for requests.post 6.

Layer 4 — requests.post Timeout (Text Embedding & Rerank)#

The text embedding and rerank model implementations do not use the openai SDK for their main invocation paths; they call the upstream endpoint directly via requests.post. Both use a fixed timeout=60 (60 seconds):

• Text embedding (text_embedding.py): requests.post(..., timeout=60) 7
• Rerank (rerank.py): requests.post(..., timeout=60) for both text and multimodal paths 8 9

Like Layer 3, these are hard-coded in plugin source and cannot be overridden via environment variables.

Configuration Reference#

Key files:

• api/configs/feature/__init__.py — PluginConfig with PLUGIN_DAEMON_TIMEOUT
• api/core/plugin/impl/base.py — timeout resolution and shared httpx.Client
• models/openai_api_compatible/models/common_openai.py — OpenAI SDK timeout kwargs
• models/openai_api_compatible/models/llm/llm.py — validation-path timeout
• models/openai_api_compatible/models/text_embedding/text_embedding.py — embedding requests.post timeout
• models/openai_api_compatible/models/rerank/rerank.py — rerank requests.post timeout