Custom Tool HTTP Timeout Configuration#

Custom and API-based tools in Dify use two independent layers of timeout configuration: one specific to the ApiTool execution class, and one at the shared SSRF proxy transport layer. Neither is configurable per-tool from the UI — both are set via environment variables at deployment time.

Layer 1 — ApiTool-Level Timeout (API_TOOL_DEFAULT_*)#

The ApiTool class in api/core/tools/custom_tool/tool.py is the runtime that executes all custom (API-based) tool calls defined via OpenAPI schemas. At module load, it reads two environment variables to construct a connect/read timeout tuple 1:

This tuple is passed directly as the timeout argument on every call to ssrf_proxy.* inside do_http_request() 2. Because the value is baked in at import time using os.getenv(), the process must be restarted for changes to take effect.

Note: These values differ intentionally from the SSRF layer defaults (5 s each). The ApiTool layer provides the effective timeout for tool calls; the SSRF proxy only applies its own defaults when no timeout kwarg is present, which is never the case for ApiTool invocations.

Layer 2 — SSRF Proxy Fallback Timeouts (SSRF_DEFAULT_*)#

make_request() in api/core/helper/ssrf_proxy.py is the shared transport used by the ApiTool and many other Dify subsystems. When no timeout kwarg is passed by the caller, it constructs an httpx.Timeout from four dify_config values 3:

These are Pydantic PositiveFloat fields on HttpConfig in api/configs/feature/__init__.py. They apply as fallback defaults for any subsystem that calls ssrf_proxy.* without specifying timeout — but not for ApiTool, which always passes API_TOOL_DEFAULT_TIMEOUT explicitly.

How the Two Layers Interact#

Custom Tool invocation
        │
        ▼
  ApiTool.do_http_request()
  timeout = (API_TOOL_DEFAULT_CONNECT_TIMEOUT, API_TOOL_DEFAULT_READ_TIMEOUT)
        │
        ▼
  ssrf_proxy.make_request(timeout=...)
  ↳ "timeout" kwarg IS present → SSRF_DEFAULT_* values are SKIPPED
        │
        ▼
  httpx.Client.send(request)

Because ApiTool always supplies an explicit timeout, the SSRF_DEFAULT_* variables have no effect on custom tool calls 3 2.

Key Source Files#