langgenius / langgenius/dify

AgentAppGenerator raises ValueError when self-hosted has no AGENT_BACKEND_BASE_URL set

Open Beginner friendly
#38,408 1 comment 1 reaction 0 assignees View on GitHub
🐞 bug 1.15.0 project#dify
Dominant language
TypeScript
Stars
156k
Forks
24.6k
Avg merge
22h 9m
Merged PRs (30d)
610

Description

### Self Checks

- [x] I have read the [Contributing Guide](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md) and [Language Policy](https://github.com/langgenius/dify/issues/1542).
- [x] This is only for bug report, if you would like to ask a question, please head to [Discussions](https://github.com/langgenius/dify/discussions/categories/general).
- [x] I have searched for existing issues [search for existing issues](https://github.com/langgenius/dify/issues), including closed ones.
- [x] I confirm that I am using English to submit this report, otherwise it will be closed.
- [x] 【中文用户 & Non English User】请使用英语提交,否则会被关闭 :)
- [x] Please do not modify this template :) and fill in all the required fields.

### Dify version

main branch (uncommitted)

### Cloud or Self Hosted

Self Hosted (Source)

### Steps to reproduce

Discovered by peaks-loop code-sweep on 2026-07-02.

1. Install Dify v1.15.0 self-hosted (Docker) with default config. Confirm `AGENT_BACKEND_BASE_URL` is unset (defaults to `None` in `configs/extra/agent_backend_config.py`).
2. Enable Agent V2 (`AGENT_STRATEGY=function_call` or `cot`) in `.env`.
3. Open an Agent app and send any chat message.
4. Observe HTTP 500 with the body `{"error": "base_url is required when creating a real agent backend client"}`. The full stack trace points at `clients/agent_backend/factory.py:21`.

### ✔️ Expected Behavior

A self-hosted deployment without `AGENT_BACKEND_BASE_URL` should automatically fall back to the in-process fake client (`FakeAgentBackendRunClient(scenario=fake_scenario)`), which is the documented behavior for users who do not configure an explicit agent backend. No HTTP 500.

### ❌ Actual Behavior

In Dify v1.15.0 with Agent V2 enabled, `AgentAppGenerator` raises `ValueError("base_url is required when creating a real agent backend client")` from `clients/agent_backend/factory.py:21` when a self-hosted deployment has not set `AGENT_BACKEND_BASE_URL` (which defaults to `None` in `configs/extra/agent_backend_config.py`).

The raise is unhelpful for default-config users: it surfaces at request time inside `_generate_worker` (`core/app/apps/agent_app/app_generator.py:331`) and aborts every Agent app call with HTTP 500, even though the in-process fake client is perfectly capable of serving the request end-to-end.

**Proposed change:** In `api/clients/agent_backend/factory.py`, `create_agent_backend_run_client()` should treat a missing or empty `base_url` the same as `use_fake=True` — return a `FakeAgentBackendRunClient(scenario=fake_scenario)` instead of raising.

- Self-hosted deployments that want the real backend: set `AGENT_BACKEND_BASE_URL` to a non-empty value (they implicitly disable the fake by providing a real URL).
- Self-hosted deployments that want the fake explicitly: pass `use_fake=True`, unchanged.
- Tests the existing `FakeAgentBackendRunClient` and `DifyAgentBackendRunClient` test suites still apply (one new branch covered, no existing test should regress).

**Risk:** When `base_url` is provided, the function still constructs a real `DifyAgentBackendRunClient` — unchanged. When `use_fake=True`, the function still returns the fake client — unchanged. The new behavior only activates when `base_url` is None or `not base_url.strip()`. Self-hosted deployments that intentionally want the real backend must provide a real URL — which is what `AGENT_BACKEND_BASE_URL` already documents. No schema, migration, controller, or frontend changes.

Contributor guide

Open the contributing guide

Research direction

Start in api/clients/agent_backend/factory.py and trace create_agent_backend_run_client(), then review the existing FakeAgentBackendRunClient and DifyAgentBackendRunClient test suites. Reproduce the default self-hosted configuration with Agent V2 enabled, add coverage for a missing or blank AGENT_BACKEND_BASE_URL, and verify that configured real and explicit fake clients remain unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.