La herramienta de migración de SharePoint omite archivos con rutas largas: causa raíz y solución

Cuando migra archivos a SharePoint con la herramienta de migración de SharePoint, algunos archivos pueden omitirse sin un error obvio. El registro de migración muestra una advertencia de que la ruta del archivo supera los 400 caracteres. Esto sucede porque Windows y SharePoint aplican un límite máximo de longitud de ruta que la herramienta respeta. Este artículo explica por qué la herramienta de migración de SharePoint omite archivos con rutas largas y proporciona una solución para resolver el problema.

Por qué la herramienta de migración de SharePoint omite archivos con rutas largas

La herramienta de migración de SharePoint utiliza la API del sistema de archivos de Windows para leer los archivos de origen. De forma predeterminada, Windows tiene una longitud máxima de ruta de 260 caracteres, conocida como MAX_PATH. Este límite se aplica a la ruta total desde la letra de unidad hasta el nombre del archivo, incluidos los caracteres de barra invertida. Cuando una ruta de archivo supera los 260 caracteres, la API de Windows no puede acceder al archivo y SPMT lo omite.

SharePoint Online admite rutas de hasta 400 caracteres en una biblioteca de documentos. Sin embargo, la herramienta de migración primero debe leer el archivo desde el origen local. Si la ruta de origen tiene más de 260 caracteres, la herramienta no puede abrir el archivo para cargarlo. El registro de migración registra una advertencia con el mensaje “La ruta del archivo es demasiado larga” y el archivo se omite.

Esta limitación no es un error de SPMT. Es una restricción del sistema de archivos subyacente de Windows. El mismo problema ocurre cuando intenta copiar, mover o eliminar un archivo con una ruta de más de 260 caracteres en el Explorador de archivos. La solución requiere habilitar la compatibilidad con rutas largas en Windows o acortar la estructura de carpetas de origen antes de la migración.

Pasos para solucionar el problema de omisión de archivos con rutas largas

Hay dos métodos para resolver este problema. El método 1 habilita la compatibilidad con rutas largas en la máquina Windows donde se ejecuta SPMT. El método 2 reduce la profundidad de las carpetas en la unidad de origen. Use el método 1 si no puede cambiar la estructura de carpetas de origen. Use el método 2 si prefiere evitar cambios en el Registro.

Método 1: Habilitar la compatibilidad con rutas largas en Windows

1. Abrir el Editor del Registro
   Presione la tecla Windows + R, escriba regedit y presione Entrar. Haga clic en Sí si el Control de cuentas de usuario se lo solicita.
2. Navegar a la clave LongPathsEnabled
   En el panel izquierdo, vaya a HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem. Desplácese hacia abajo para encontrar la entrada LongPathsEnabled.
3. Modificar el valor a 1
   Haga doble clic en LongPathsEnabled. Cambie los datos del valor de 0 a 1. Haga clic en Aceptar.
4. Reiniciar el equipo
   Cierre el Editor del Registro y reinicie el equipo. Este cambio habilita la compatibilidad con rutas largas para todas las aplicaciones que lo admitan, incluida SPMT.
5. Ejecutar SPMT de nuevo
   Abra la herramienta de migración de SharePoint e inicie la misma tarea de migración. Ahora se pueden leer y cargar archivos con rutas de hasta 32.767 caracteres.

Método 2: Acortar la estructura de carpetas de origen

1. Identificar carpetas con anidamiento profundo
   Abra la carpeta de origen en el Explorador de archivos. Busque carpetas anidadas a más de 5 niveles de profundidad. Cada nivel de carpeta aumenta la longitud de la ruta.
2. Mover archivos a una carpeta raíz más corta
   Cree una nueva carpeta directamente en la raíz de la unidad, por ejemplo C:\Migrate. Copie los archivos y carpetas desde la ubicación profunda a esta nueva carpeta. Esto reduce la longitud de la ruta inicial.
3. Cambiar el nombre de las carpetas a nombres más cortos
   Si no es posible mover los archivos, cambie el nombre de las carpetas a caracteres individuales o números. Por ejemplo, cambie el nombre “Department of Finance and Accounting” a “FinAcct”. Esto reduce la longitud total de la ruta.
4. Eliminar carpetas intermedias innecesarias
   Elimine las carpetas que no tengan ningún propósito, como “Archive” u “Old” dentro de una estructura profunda. Combine varias carpetas vacías en una sola.
5. Ejecutar SPMT con la ruta de origen acortada
   Apunte SPMT a la nueva ubicación de carpeta más corta. Verifique que no se omita ningún archivo debido a la longitud de la ruta.

Si la herramienta de migración sigue omitiendo archivos después de la solución

El registro de SPMT muestra que la ruta del archivo sigue siendo demasiado larga

Si aplicó el método 1 pero los archivos siguen omitiéndose, confirme que el cambio en el Registro haya surtido efecto. Abra el Editor del Registro de nuevo y verifique que LongPathsEnabled esté establecido en 1. Además, asegúrese de haber reiniciado el equipo después del cambio. Es posible que algunas versiones anteriores de SPMT no admitan rutas largas. Actualice SPMT a la versión más reciente desde el Centro de descargas de Microsoft.

El nombre del archivo contiene caracteres no válidos

Un archivo con una longitud de ruta válida aún puede omitirse si su nombre contiene caracteres que SharePoint no permite. Los caracteres no válidos incluyen ~ # % & : < > ? / \ |. Cambie el nombre del archivo en el origen para eliminar estos caracteres antes de ejecutar SPMT de nuevo.

SPMT informa acceso denegado para el archivo

Si la ruta del archivo es lo suficientemente corta pero SPMT no puede leer el archivo, verifique los permisos del archivo. Haga clic con el botón derecho en el archivo, seleccione Propiedades, vaya a la pestaña Seguridad y verifique que su cuenta tenga permiso de Lectura. Si no es así, tome posesión del archivo o pida al administrador que conceda acceso.

Elemento	Cambio en el Registro (Método 1)	Reestructuración de carpetas (Método 2)
Efecto en los archivos de origen	Ninguno	Mueve o cambia el nombre de los archivos
Requiere derechos de administrador	Sí	No
Requiere reinicio	Sí	No
Funciona para todas las migraciones futuras	Sí	No
Riesgo de romper otras aplicaciones	Bajo	Ninguno

Ahora puede ejecutar la herramienta de migración de SharePoint sin que se omitan archivos debido a rutas largas. Si habilitó el cambio en el Registro, recuerde volver a establecer LongPathsEnabled en 0 después de la migración si no necesita compatibilidad con rutas largas para otras aplicaciones. Para migraciones continuas, considere usar la herramienta de migración de SharePoint con scripts de PowerShell que incluyan una comprobación de longitud de ruta antes de la transferencia.