bytedance/deer-flow · error · HTTPException

Failed to update MCP configuration: {str(e)}

Error message

Failed to update MCP configuration: {str(e)}

What it means

500 raised when _apply_mcp_config_update fails with an unexpected (non-HTTP) exception while applying a full MCP config update: JSON decode errors in extensions_config.json, permission failures writing the file, pydantic validation of stored raw entries, or errors in reload_extensions_config. The original exception is logged with traceback; its str(e) is intentionally included in the detail for diagnosability.

Source

Thrown at backend/app/gateway/routers/mcp.py:948

        await require_admin_user(request, detail=_ADMIN_REQUIRED_DETAIL)
        _validate_mcp_update_request(body)

        # Offload the blocking read-modify-write of extensions_config.json
        # (path resolve, existence probe, raw read, merged write, reload). The
        # worker takes extensions_config_write_lock for the whole RMW, so it stays
        # atomic and serialized against the skills router (the other writer of
        # this file) even if this request is cancelled mid-write.
        reloaded_servers = await asyncio.to_thread(_apply_mcp_config_update, body)

        servers = {name: _mask_server_config(McpServerConfigResponse(**server.model_dump())) for name, server in reloaded_servers.items()}
        reset_mcp_tools_cache()
        return McpConfigResponse(mcp_servers=servers)

    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Failed to update MCP configuration: {e}", exc_info=True)
        raise HTTPException(status_code=500, detail=f"Failed to update MCP configuration: {str(e)}")


@router.patch(
    "/mcp/config",
    response_model=McpConfigResponse,
    summary="Update MCP Server State",
    description="Enable or disable one MCP server without replacing the full extensions configuration.",
)
async def update_mcp_server_state(request: Request, body: McpServerStateUpdateRequest) -> McpConfigResponse:
    """Enable or disable one MCP server and reload the MCP tool cache."""
    try:
        await require_admin_user(request, detail=_ADMIN_REQUIRED_DETAIL)
        reloaded_servers = await asyncio.to_thread(_apply_mcp_server_state_update, body)

        servers = {name: _mask_server_config(McpServerConfigResponse(**server.model_dump())) for name, server in reloaded_servers.items()}
        reset_mcp_tools_cache()
        return McpConfigResponse(mcp_servers=servers)
    except HTTPException:

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Read the Gateway log line 'Failed to update MCP configuration' — the included str(e) plus traceback pinpoints the failure
2. Validate extensions_config.json parses (python -m json.tool) and fix syntax errors
3. Ensure the Gateway process can write the config file and directory (atomic rename needs directory write access)
4. If a stored entry fails validation, remove or repair it via direct file edit, then retry the API update

Example fix

# before: corrupted extensions_config.json -> 500 on every PUT
# after
python -m json.tool extensions_config.json   # locate and fix the syntax error
# then retry PUT /api/mcp/config

// pre-flight: ensure the config file parses before PUT
// python -c "import json;json.load(open('extensions_config.json'))"

null

try { await putMcpConfig(payload); } catch (e) { if (e.status === 500) { console.error('server-side apply failed:', e.detail); /* read Gateway log; fix config/permissions; retry once */ } throw e; }

When it happens

Trigger: PUT /api/mcp/config when extensions_config.json is corrupted JSON; the Gateway process lacks write permission on the config file; a pre-existing raw server entry fails model validation during reload; disk full during the atomic write.

Common situations: Hand-edited config files with syntax errors; read-only volumes in containers; concurrent external edits racing the API write; leftover invalid entries from older config schemas.

Related errors

• Failed to update MCP server state: {str(e)}
• Failed to load MCP configuration
• Failed to update MCP configuration
• Failed to update MCP server
• Failed to list agents: {str(e)}

AI-assisted analysis of bytedance/deer-flow@1dd6ba1acb (2026-08-14). Data as JSON: /api/errors/dba719d5d0df59ae. Report an issue: GitHub.