From 2195e81276c8a95f7af74db41e73cc7bcaea2a86 Mon Sep 17 00:00:00 2001 From: Shakti Prasad Mohapatra Date: Sat, 1 Aug 2026 21:21:53 +0530 Subject: [PATCH] fix: improve AGENT_BACKEND_BASE_URL error message with config guidance The Agent node (agent_v2) in Workflow/Chatflow fails with a generic 'base_url is required' error when AGENT_BACKEND_BASE_URL is not set. The standard docker/dify Compose stack doesn't include the Agent backend service, so self-hosted users hit this error with no hint about what to do. Replace the bare ValueError with a message that names the env var, explains the service requirement, and suggests the classic Agent app as an alternative. Fixes #39161 --- api/clients/agent_backend/factory.py | 11 ++++++++++- .../clients/agent_backend/test_factory.py | 19 +++++++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/api/clients/agent_backend/factory.py b/api/clients/agent_backend/factory.py index d5af6aed486..a2de492094d 100644 --- a/api/clients/agent_backend/factory.py +++ b/api/clients/agent_backend/factory.py @@ -27,7 +27,16 @@ def create_agent_backend_run_client( if use_fake: return FakeAgentBackendRunClient(scenario=FakeAgentBackendScenario(fake_scenario)) if base_url is None: - raise ValueError("base_url is required when creating a real Agent backend client") + raise ValueError( + "AGENT_BACKEND_BASE_URL is not configured. The Chatflow/Workflow Agent node " + "requires a separately deployed Agent backend service. Set the " + "AGENT_BACKEND_BASE_URL environment variable to the service's URL, " + "or use the classic Agent-type app (mode: agent-chat) which runs " + "in-process and does not require this service." + ) + headers: dict[str, str] = {} + if api_token: + headers["Authorization"] = f"Bearer {api_token}" return DifyAgentBackendRunClient( create_agent_backend_client( base_url=base_url, diff --git a/api/tests/unit_tests/clients/agent_backend/test_factory.py b/api/tests/unit_tests/clients/agent_backend/test_factory.py index 0b595adda53..943dc313c18 100644 --- a/api/tests/unit_tests/clients/agent_backend/test_factory.py +++ b/api/tests/unit_tests/clients/agent_backend/test_factory.py @@ -71,3 +71,22 @@ def test_default_agent_backend_clients_forward_authentication( factory() create_client.assert_called_once_with(base_url="http://agent-backend", api_token="secret-token") + + +def test_missing_base_url_raises_helpful_error(): + """When AGENT_BACKEND_BASE_URL is not set, the error should mention the + environment variable and suggest alternatives (issue #39161).""" + with pytest.raises(ValueError) as exc_info: + create_agent_backend_run_client(base_url=None) + + message = str(exc_info.value) + # The error must mention the env var name so users know what to set. + assert "AGENT_BACKEND_BASE_URL" in message + # The error should hint at the classic Agent app as an alternative. + assert "agent-chat" in message + + +def test_use_fake_does_not_require_base_url(): + """The fake client path should not raise even when base_url is None.""" + client = create_agent_backend_run_client(use_fake=True, base_url=None) + assert client is not None