Troubleshooting Dify outbound request failures

Why Dify outbound requests fail and how to troubleshoot them

When a tool, HTTP node, model server or external knowledge API times out or returns a 403 from inside Dify, the first thing to recognize is that the outbound path is filtered by design. Dify's SSRF_PROXY settings route outbound requests through a proxy that blocks internal and private IP ranges, as described in the environment variable reference. That protects the platform from being used to reach internal services, but it also means a request to a private host, an intranet model server or an internal knowledge API can fail even when the target is reachable from the Dify host itself. Teams usually need this troubleshooting in three situations: when they first connect an internal endpoint, after they change a network or DNS layout, or after a Dify upgrade changes how traffic leaves the containers. The proxy block is the default suspect, not the network, so check the proxy path before opening firewall rules.

The agent sandbox has its own egress path. The Dify 1.16.1 release notes describe agent sandbox network isolation through a Squid proxy, so a failing call from an agent or code step may pass through a different proxy than an HTTP node in a workflow. Before you change anything, confirm which component makes the request, which proxy it uses and which container logs show the block. Record the target host, the port, the Dify version from your .env file and whether the failure is a timeout or an explicit 403. Those four facts decide whether the fix belongs in the allowlist, the proxy configuration, the sandbox settings or the network path between containers. Confirm the exact allowlist and proxy variable names against the environment reference for your release, because they can change between versions.

A quick way to separate these cases is to test the same URL from the API container and from the sandbox context, then compare the result with a direct request from the host. A success from the host and a 403 from the container points at the proxy rule, while a timeout from both points at routing, DNS or the target service. Keep a short written record of each change, including the proxy setting, the version and the test result, because the same symptom can return after an upgrade. Ask your Dify administrator and network team to agree on who owns the proxy allowlist before the first production integration goes live, since that decision controls which internal systems your workflows can reach.

Configuration options and when each one fits

This table compares the five levers operators usually reach for when outbound requests from Dify fail, from keeping the SSRF proxy block in place to moving a model server onto an approved internal path. Read each row for when it fits and the risk it adds, and confirm exact keys in the environment variable reference before you change anything.

Lever	When it fits	Risk it adds
Keep the SSRF proxy default block	Any request that reaches a public API or a model endpoint you already expose through approved egress. Start here and treat every other lever as an exception.	Requests to private services fail until one of the other levers is applied, so the failure needs a clear owner and a documented path.
Allow a private host or network through the SSRF proxy configuration	A named internal knowledge API, tool or model server that the team has approved, reachable from the Dify network, and needed by a specific workflow.	Opens a path from workflow code to internal systems. Scope it to specific hosts or ranges, not broad private blocks, and review it when the target changes.
Adjust proxy settings for an upstream corporate proxy	Your network requires outbound traffic to pass through a corporate egress proxy, and the Dify outbound proxy must forward to it.	Misconfigured proxy values can route internal traffic out to the internet or break access to allowed destinations. Confirm the exact SSRF_PROXY keys in the environment reference first.
Raise the HTTP node or tool timeout	A slow but healthy upstream, such as a large inference call or a bulk lookup, that times out at the default limit after you have confirmed the target is responding.	Long timeouts hold worker capacity and make failing calls slower to surface. Raise the limit only for the specific nodes or tools that need it.
Move the model server or knowledge API onto an approved internal path	A self-hosted model endpoint or external knowledge system that should be reached through a managed gateway, service address or documented internal route rather than an ad hoc exception.	Needs network changes, DNS and certificate work, and coordination with the owning team. Usually the most durable option but the slowest to deliver.

Diagnosing 403 errors versus timeouts by destination

Tools and HTTP nodes make their requests from the api or worker containers, so the outbound path runs through the SSRF proxy included in the Docker Compose deployment. A 403 usually means the destination received the request and refused it, while a timeout means the request did not finish within the time allowed. Separate those two cases in the run log before you change anything.

Private address blocked: the SSRF proxy blocks internal and private IP ranges, so a URL that resolves to a private host can fail even when a browser on your network opens it.
Destination refusal: a 403 returned by the target often points to a missing or expired credential, a header the API rejects, or an IP allowlist on the vendor side.
Node timeout: compare the destination's measured response time with the timeout set on the HTTP node, then check whether the workflow waits on a slow upstream step.
Proxy variables: if you set an outbound proxy for the containers, confirm that internal hosts you call directly are excluded from it.

Check the status and response body the HTTP node records, then the api container log at the same timestamp, and map the result to a network policy change, a credential fix or a workflow timeout change.

Model providers are called by the api and worker containers, and self-hosted inference servers often sit on private addresses. That makes the private-range rule in the SSRF proxy the first suspect when a model endpoint is unreachable from Dify but responds to your administrators. A 403 from a model gateway is usually a credential or policy decision made at the gateway, while a timeout often reflects a server still loading a model or a queue of waiting requests.

Private endpoint blocked: an inference server on a private address may be refused by the proxy even though the host reaches it directly.
Localhost confusion: an address that works in a host shell can point to the container itself when it uses localhost, so use a hostname or interface the container can reach.
Gateway credential or policy: a 403 from a gateway often traces to the API key, its scope or a source network rule configured on the gateway.
Cold start and queueing: long first responses can exceed the timeout while the model loads, so read the inference server's own log for the same window.
Plugin health: model providers run through plugins, so confirm the plugin daemon is running before you blame the endpoint.

Run the same request with curl from inside the api container, compare the result with the Dify run log, and decide whether the fix is a proxy rule, a gateway policy or inference capacity.

Agent sandboxes run code and tool calls in their own environment, and Dify 1.16.1 added agent sandbox network isolation through a Squid proxy. Failures on this path can resemble the HTTP node problems in the first tab, but they involve a different proxy and a different allowlist, so the log you read first changes. Confirm which path a failing run used before you apply any fix.

Separate proxy path: agent sandbox traffic passes through the Squid proxy, so a destination can fail there even when the api container reaches it.
Version dependence: isolation behavior depends on the running version, so confirm your version before comparing logs with release notes or older runs.
Egress rules: Squid decides which destinations are allowed, so review the rule set in your configuration before changing anything else.
Container boundaries: the api, the SSRF proxy and the code sandbox are separate containers, so read the log of each one for the same run.
Upgrade path: if failures began after an upgrade, check the Dify releases on GitHub for the version you moved to and the .env.example file for new variables.

Pull the sandbox and proxy logs for the failing run, identify which container refused or dropped the connection, and apply the egress rule, version or upgrade fix that matches.

Step-by-step diagnosis of a blocked or timed-out request

This sequence moves from a reproduced failure to a confirmed cause, a targeted configuration change and a passing retest, so the team fixes the actual blocker instead of loosening network controls by guesswork. It is written for the operator who owns the Compose host and the Dify environment file.

Reproduce the failure from the calling container
Run the same request from inside the container that makes the call, not from the host or a laptop, because the api and worker containers sit on a different network path and carry their own proxy environment. Use docker compose exec against the worker or api service and issue a single request to the exact URL the tool, HTTP node or knowledge API uses, capturing the status code, the time taken and any error text. The step is done when you have one reproducible result you can compare against later, such as a 403 response, a connection timeout or a DNS failure.
Identify the destination address and whether it is private
Resolve the hostname from inside the same container and record every address returned, both IPv4 and IPv6, because a name can resolve to a private range in one environment and a public one in another. Check whether any returned address falls in a loopback, link-local, or private range, since the SSRF proxy is designed to block internal and private IP ranges by default. The step is done when you can state, for the specific destination, its address family and whether it is classed as private, and you have noted any mismatch between the name you configured and the address it resolves to.
Check the SSRF proxy and Dify logs
Inspect the logs of the SSRF proxy container and the api and worker containers around the time of your reproduced request, using docker compose logs with a time window or a follow filter. Look for a proxy denial or a 403 originating from the proxy rather than from the remote service, which tells you the request never left the platform. Confirm whether the error is a proxy block, a connection timeout at the proxy, or a response from the target server. The step is done when you can name which component produced the failure, because the fix differs for each.
Adjust the allowlist or proxy settings
Change only the setting that matches the cause you confirmed. If the proxy blocked a private destination that your organization owns and has approved, add it through the SSRF proxy configuration your environment supports, and confirm the exact key names in the Dify environment reference before editing. If the container needs an outbound proxy to reach a public host, set the proxy variables for the service that makes the call and keep your no-proxy list covering internal names. Record each change in your change log with the old value, the new value and the reason. The step is done when the edit is saved in the environment file and the change is limited to the single destination you diagnosed.
Restart the affected services after changing .env
Environment changes are read when a container starts, so editing .env alone does not change running services. Recreate the containers that consume the changed value, typically api, worker and the proxy container, rather than rebuilding the whole stack, and confirm that each one picked up the new environment by checking its configuration from inside the container. Compare your .env against .env.example if the release you run added variables. The step is done when the recreated containers report healthy status and the new value is visible inside them.
Verify with the same request from the same container
Repeat the exact request from step one, from the same container, using the same URL, method and headers, and record the status code and elapsed time. A pass means the response matches what the destination should return, not merely a successful connection, so confirm the body or status is what the workflow expects. If the request still fails, return to the proxy and application logs rather than widening the allowlist further. The step is done when the reproduced request succeeds and a test run of the affected tool, HTTP node or knowledge sync also completes.

Security trade-offs of loosening outbound filtering

Every fix for a blocked outbound request moves a boundary. The SSRF proxy, private host allowlists, tool credentials and sandbox egress each decide whether a workflow can reach internal services it should never touch. Review each change against the SSRF exposure it creates and the service authentication and sandbox controls that Dify 1.16.1 added.

Allowing private IP ranges

The SSRF proxy blocks internal and private IP ranges by default, so a 403 on a tool or HTTP node is often the control working as designed. Allowing private ranges broadly lets any workflow author point a node at metadata endpoints, admin panels or database ports on your network. Before you change the setting, identify the single host or service that needs access and confirm that the proxy rules, not the application, are the place where that exception lives.

Broad host allowlists

A wildcard or domain-suffix allowlist can quietly include hosts you never meant to trust, including subdomains you do not control or services that redirect to internal addresses. Each entry should map to a named integration with an owner and a reason. Review the list when a workflow is retired, because stale entries keep an outbound path open after the business need has ended.

Disabling the SSRF proxy

Pointing outbound traffic directly at the network, or bypassing the proxy container, removes the one component that enforces the private-range block for every node at once. Without it, a single unreviewed tool can reach internal addresses from the api or worker containers, which hold database and Redis connectivity. If troubleshooting requires a temporary bypass, record it, scope it to one host and restore the proxy path the same day.

Credentials in tool configuration

API keys stored in a tool or HTTP node configuration are visible to anyone who can edit the app, and they travel with exported DSL only if they are not handled as secrets. Use Dify's credential handling for each provider and keep the tool definition free of raw tokens. Changing SECRET_KEY later logs users out, so plan secret rotation separately from any outbound allowlist change.

Token-based service authentication

Dify 1.16.1 added token-based API authentication between services, which limits what an internal caller can do without a valid token. Loosening outbound rules does not replace that control, but it does widen the set of internal endpoints a compromised workflow can attempt to reach. Confirm which internal services in your deployment enforce the token check before you open a path to them.

Sandbox egress and template rendering

Dify 1.16.1 isolated agent sandbox network traffic through a Squid proxy and sandboxed Jinja2 template rendering. Sandbox egress rules should stay at least as strict as the HTTP node rules, because code run in the sandbox can make the same calls. When a sandboxed tool fails with a timeout or 403, check the sandbox proxy logs and the allowlist for that path separately rather than copying the HTTP node exception into it.

Questions operators ask before fixing outbound failures

How long does a typical fix for outbound request failures take?

The duration depends on how many outbound paths are failing and whether the cause is a single setting or several layers at once. A 403 from the SSRF proxy on one HTTP node is usually a narrow change, while a mix of blocked private hosts, missing proxy exceptions and timeouts across tools and knowledge APIs takes longer because each path must be traced separately. Ask any partner for a written scope that lists the paths in question, the environment where testing happens, and the verification steps for each path. No general duration is supplied for this work, so confirm the estimate against your own list of failing integrations before you plan a change window.

Can an internal team fix Dify outbound failures without outside help?

Often yes, if the team can read Dify logs, understand Docker Compose networking and has authority to edit the .env file and restart services. The work involves identifying which component makes the request (a tool, an HTTP node, a model server or an external knowledge API), checking whether the SSRF proxy blocks the destination, and confirming the network route from the container. Teams without someone who knows container networking or proxy configuration tend to take longer and may loosen controls too far. An outside partner adds most value when the failures cross several integrations or when the change needs documented evidence for a review.

What should we provide to a partner before they start?

Prepare a list of the failing paths, not just the error. For each one, include the Dify version, the deployment method, the destination host or service name, the node or tool that calls it, the exact error and the timestamp of a recent occurrence. Also provide the current values of the proxy-related settings from your .env file with secrets removed, the network layout between Dify and the target services, and any internal ranges your security team already allows. Access to a non-production copy of the environment speeds up testing, and written approval for any change to the SSRF proxy policy should be settled before work starts.

Does changing SSRF_PROXY settings require a downtime window?

Changing environment values generally requires restarting the services that read them, so plan a short window for the api and worker containers at minimum. The Dify environment reference explains that SSRF_PROXY settings route outbound requests through a proxy that blocks internal and private IP ranges, which means any change to allowed destinations affects every feature that makes outbound calls. Test the change on a copy first, then apply it during a window agreed with the users who run workflows and indexing jobs. Confirm the exact restart sequence for your deployment method in the Docker Compose documentation before you schedule it.

How do Dify upgrades affect these outbound settings?

Upgrades can change the default values, the file layout and the set of variables that control outbound traffic, so these settings should be reviewed each time you move to a new version. The Dify Docker Compose documentation says to follow the upgrade guide for the target version on the GitHub Releases page, to take a backup before every upgrade and to check .env.example for new variables afterward. The 1.16.1 release notes also describe agent sandbox network isolation through a Squid proxy, which changes how sandboxed code reaches the network. Compare your custom proxy values with the new template before restarting, and retest the failing paths after each upgrade.

Does fixing outbound request failures change our compliance evidence?

Yes, the change becomes part of your control record, so it should be documented with the reason for each allowed destination, the approver and the test that proved the path works. Changes to the SSRF proxy affect which internal ranges Dify can reach, which is a network access decision your auditors may ask about. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports or certifications, and independent auditors and certification bodies make that determination. Ask your assessor which evidence format they expect for network access changes before you start.

Which settings should stay tightly restricted after the fix?

Keep the default blocking of internal and private ranges unless a specific destination has a documented business need. Add exceptions one host or one service at a time, rather than opening whole subnets, and record each exception with an owner and a review date. Avoid disabling the proxy for convenience, because the proxy is the control that stops a workflow or tool from reaching internal services it should not touch. Review the list after every upgrade, since new sandbox and proxy behavior in later releases can change what traffic is allowed.

Limits to confirm in your environment

Most outbound failures in a self-hosted Dify come from a handful of settings that differ between versions and networks. The cards below list what to confirm for your release and your network before you change proxy rules, allowlists or timeouts.

Exact SSRF proxy keys for your version

The SSRF_PROXY settings route outbound requests through a proxy that blocks internal and private IP ranges, but the exact variable names and allowlist behavior depend on the release you run. Read the environment variable reference for your version and compare it with the .env.example file shipped in your deployment. Do not copy keys from forum posts or older guides without checking them against that version.

Private addresses behind model and knowledge hosts

A model server or external knowledge API on a private address can be blocked by the SSRF proxy even when it is reachable from the Dify host. Resolve each hostname from inside the api and worker containers, not from your workstation, because DNS views often differ. Record which endpoints resolve to private ranges so you know which ones need a deliberate exception.

Corporate proxy behavior

If your organization forces outbound traffic through a corporate proxy, the Dify containers may need proxy variables of their own, and the SSRF proxy may then send internal endpoints through the wrong path. Confirm whether your proxy intercepts traffic to internal hostnames, applies TLS inspection, or enforces its own allowlist. Test the same URL from inside the container with the same settings Dify uses.

HTTP node timeout ceiling

An HTTP node in a workflow stops waiting once it reaches the timeout ceiling configured for your deployment, and a slow model or API can look like a network block. Confirm the ceiling and the per-node timeout your version applies, then compare it with the response time of the endpoint under load. Raise the limit only after you know whether the delay is network or application time.

Sandbox proxy changes in your release

Dify 1.16.1 changed agent sandbox network isolation to run through a Squid proxy, which can alter how sandboxed tools reach hosts that worked before. Check the releases page for the minor version you run and confirm whether it includes these changes. If you are on an earlier release, expect different behavior and test sandboxed tools separately.

How DeployOpen scopes and fixes outbound request issues

DeployOpen approaches outbound request failures in Dify by first mapping which tools, HTTP nodes, model servers and external knowledge APIs call out, and from where. The work then isolates whether each failure comes from the SSRF proxy, a private host allowlist, a timeout or a proxy setting, and fixes it inside your own infrastructure.

How we scope

Inventory every tool, HTTP node, model endpoint and external knowledge API that calls out from Dify.
Record the target hosts, protocols, network zones and proxy path for each outbound request.
Agree in writing which failures, environments and Dify versions the fixed scope covers.

How we build

Reproduce each timeout or 403 from the affected container and capture the matching logs.
Adjust SSRF proxy settings, private host allowlists and proxy variables under change control, one step at a time.
Test each fix against the original request path, then confirm the change in staging before production.

How we hand over

Deliver a written record of each allowed destination, its owner, and the reason it is permitted.
Document the environment variables changed, their previous values and the rollback steps for each.
Walk your operators through the diagnostic commands and the checks to repeat after each Dify upgrade.

How we support

Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
Ongoing support, upgrades and continuous testing are available as a retainer.
Quotes follow from the written scope, so ask us to confirm which destinations and environments are included.