La URL relativa al servidor debe comenzar con la URL relativa al servidor de SPWeb: causa raíz y solución

Al personalizar páginas de SharePoint, agregar elementos web o trabajar con soluciones de SharePoint Framework, es posible que veas el error: “Server relative URL must start with SPWeb server relative URL”. Este error impide que una página o elemento web se cargue correctamente. La causa raíz es una discrepancia entre la URL que proporcionaste en tu código o configuración y la ruta relativa al servidor real del sitio de SharePoint. Este artículo explica exactamente por qué ocurre este error y cómo solucionarlo utilizando el formato de URL correcto.

Por qué ocurre el error de URL relativa al servidor

SharePoint utiliza URL relativas al servidor para hacer referencia a recursos como páginas, listas y archivos dentro de una colección de sitios. Una URL relativa al servidor omite el protocolo y el dominio, comenzando con la ruta administrada, por ejemplo /sites/MySite o /teams/MyTeamSite. El error “Server relative URL must start with SPWeb server relative URL” se produce cuando la URL proporcionada no comienza con la misma ruta que el objeto web de SharePoint (SPWeb) actual.

El objeto SPWeb representa un sitio de SharePoint específico, que podría ser el sitio raíz de una colección de sitios o un subsitio. Cada SPWeb tiene una propiedad ServerRelativeUrl. Por ejemplo, un sitio en https://contoso.sharepoint.com/sites/Projects/Subsite tiene una URL relativa al servidor de /sites/Projects/Subsite. Si intentas establecer la URL de una página a /sites/Projects/Pages/Home.aspx, la URL es válida para la raíz de la colección de sitios pero no para el subsitio. La URL correcta para el subsitio sería /sites/Projects/Subsite/Pages/Home.aspx.

Escenarios comunes que desencadenan el error

El error aparece en varias situaciones:

• Elementos web de SharePoint Framework (SPFx): Cuando codificas una URL relativa al servidor en una propiedad del elemento web en lugar de usar el contexto de la página.
• Diseños de página personalizados o páginas maestras: Cuando un enlace o referencia de recurso utiliza una URL que no comienza con la ruta relativa al servidor del sitio actual.
• Scripts de PowerShell o código CSOM: Cuando pasas una URL relativa al servidor a un método que espera que la URL sea relativa al SPWeb actual.
• Flujos de trabajo de SharePoint Designer: Cuando una acción de flujo de trabajo hace referencia a una lista o biblioteca utilizando una URL absoluta o relativa mal formada.

El problema central es siempre el mismo: la URL que proporcionaste no comienza con la misma ruta que el sitio en el que estás trabajando.

Pasos para solucionar el error de URL relativa al servidor

Método 1: Corregir la URL en elementos web de SharePoint Framework

1. Identifica la URL relativa al servidor del web actual
   En el código de tu elemento web SPFx, usa this.context.pageContext.web.serverRelativeUrl para obtener la ruta base correcta. Para un sitio en /sites/MySite, esta propiedad devuelve /sites/MySite.
2. Antepón la ruta base a tu URL de destino
   En lugar de escribir /sites/MySite/Lists/Tasks, construye la URL dinámicamente: this.context.pageContext.web.serverRelativeUrl + '/Lists/Tasks'. Esto asegura que la URL final comience con la ruta SPWeb correcta.
3. Prueba el elemento web en un sitio diferente
   Implementa el elemento web en un subsitio. Verifica que la URL se actualice automáticamente para incluir la ruta del subsitio. Si el elemento web aún usa una URL codificada, el error reaparecerá.

Método 2: Corregir URLs en código CSOM o PowerShell

1. Obtén el objeto SPWeb
   En CSOM, usa clientContext.Web para obtener el web actual. En PowerShell, usa Get-SPWeb con la URL del sitio.
2. Lee la propiedad ServerRelativeUrl
   Para el objeto web, accede a $web.ServerRelativeUrl (PowerShell) o web.ServerRelativeUrl (CSOM). Almacena este valor en una variable.
3. Construye la ruta relativa al servidor completa
   Combina la URL relativa al servidor del web con la ruta relativa del recurso. Ejemplo: $web.ServerRelativeUrl + '/Lists/MyList'. No incluyas el dominio absoluto.
4. Valida la URL final
   Verifica que la URL combinada comience con la URL relativa al servidor del web. Si no es así, ajusta la ruta del recurso para que sea relativa a la raíz del web.

Método 3: Corregir URLs en diseños de página y páginas maestras

1. Usa el token ~sitecollection
   En SharePoint Designer o HTML, reemplaza las rutas codificadas con ~sitecollection o ~site. El token ~sitecollection se resuelve a la URL relativa al servidor de la colección de sitios. El token ~site se resuelve a la URL relativa al servidor del sitio actual.
2. Reescribe URLs absolutas
   Si un enlace usa una URL absoluta como https://contoso.sharepoint.com/sites/MySite/Pages/Home.aspx, cámbiala a ~site/Pages/Home.aspx. Esto asegura que el enlace funcione en cualquier sitio dentro de la colección.
3. Prueba con un subsitio
   Navega a un subsitio y verifica que todos los enlaces y recursos se carguen sin el error. Si el error persiste, verifica que el token se haya resuelto a la ruta correcta.

Si el error persiste después de la solución principal

“Server Relative URL Must Start With SPWeb Server Relative URL” en SharePoint Designer

Al editar una página en SharePoint Designer, es posible que veas este error después de cambiar la URL de un recurso vinculado. La causa suele ser una URL codificada en un elemento web de vista de datos o en un hipervínculo. Para solucionarlo, abre la página en modo avanzado, encuentra la URL del recurso y reemplázala con un token o una URL relativa al servidor que comience con la ruta del sitio actual. Usa ~site para recursos que deben seguir al sitio actual.

Error al agregar un elemento web mediante programación

Si agregas un elemento web mediante código y proporcionas una URL relativa al servidor para una propiedad como ContentLink, asegúrate de que la URL sea relativa al web donde se agrega el elemento web. Por ejemplo, si agregas un elemento web a un subsitio en /sites/MySite/Subsite, la URL debe comenzar con /sites/MySite/Subsite. Un error común es usar la ruta raíz de la colección de sitios en su lugar. Siempre obtén la URL relativa al servidor del web actual dinámicamente.

Validación de URL en el panel de propiedades de SharePoint Framework

En SPFx, si tienes un campo del panel de propiedades que acepta una URL relativa al servidor, el usuario podría ingresar un valor incorrecto. Agrega validación a tu elemento web que verifique si la URL ingresada comienza con this.context.pageContext.web.serverRelativeUrl. Si no es así, muestra un mensaje de error y evita que el elemento web se renderice. Esto detecta el problema antes de que ocurra el error.

URL relativa al servidor vs URL absoluta vs URL relativa al sitio

Elemento	URL relativa al servidor	URL absoluta	URL relativa al sitio
Formato	/sites/MySite/Pages/Home.aspx	https://contoso.sharepoint.com/sites/MySite/Pages/Home.aspx	/Pages/Home.aspx
Incluye dominio	No	Sí	No
Incluye ruta administrada	Sí	Sí	No
Funciona entre colecciones de sitios	Sí	Sí	No
Funciona entre subsitios	Sí	Sí	No
Caso de uso común	APIs, SPFx, CSOM	Enlaces externos, correos electrónicos	Navegación dentro del mismo sitio, imágenes

El error solo se aplica a URL relativas al servidor. Si usas una URL absoluta, SharePoint normalmente la acepta pero puede seguir lanzando el error si el código espera explícitamente una URL relativa al servidor. El enfoque más seguro es usar siempre URL relativas al servidor construidas a partir del contexto del web actual.

Ahora puedes identificar y solucionar el error “Server relative URL must start with SPWeb server relative URL”. Usa siempre métodos dinámicos para obtener la URL relativa al servidor del web actual, ya sea en SPFx, PowerShell o diseños de página. Para soluciones complejas, prueba tanto en sitios raíz como en subsitios para detectar discrepancias de ruta temprano. Una práctica confiable es almacenar la URL relativa al servidor del web en una variable al inicio de tu código y anteponerla a cada ruta de recurso.