Xcode se queja «No such module», aunque el framework está en su lugar: ¿qué hacer?

«No such module»: la pesadilla familiar de todo desarrollador Swift

Añades un framework a través de SPM, CocoaPods o manualmente, lo ves en el Project Navigator, todo parece perfecto — pero Xcode obstinadamente escribe: No such module 'Alamofire' (o cualquier otro módulo). ¿Te suena? Si es así — no estás solo. La pregunta original en Stack Overflow ha acumulado decenas de miles de visitas, y los comentarios se han convertido en una verdadera colección del dolor de los desarrolladores de iOS.

En este artículo, analizaremos 10 causas reales por las que ocurre el error No such module y mostraremos cómo solucionarlas. Al final, te espera una lista de verificación que te ahorrará horas de nervios.

¿Por qué Xcode no ve el módulo? Top 10 causas

1. Derived Data — el principal culpable

Xcode almacena en caché la información del proyecto en la carpeta Derived Data. Si la caché está desactualizada o dañada, el compilador «olvida» los módulos conectados. Esto es lo primero que hay que verificar.

Cómo solucionarlo:

\n
• Cierra Xcode
\n
• Abre la terminal y ejecuta:\n

  rm -rf ~/Library/Developer/Xcode/DerivedData

  \n
\n
• O manualmente: Xcode → Preferences → Locations → Derived Data → haz clic en la flecha → elimina la carpeta
\n
• Reinicia Xcode y presiona Cmd + B
\n

2. Configuración incorrecta de Build Phases

Incluso si el framework está físicamente en el proyecto, Xcode puede no saber que debe enlazarlo. Verifica Link Binary With Libraries:

\n
• Selecciona el target → Build Phases
\n
• Despliega Link Binary With Libraries
\n
• Asegúrate de que tu framework esté ahí
\n
• Si no está — presiona + y agrégalo
\n

3. Swift Package Manager: rama o versión incorrecta

SPM es una herramienta conveniente, pero es sensible a las versiones. Si especificaste from: "1.0.0" y en el repositorio hay una versión 2.0.0, Xcode puede no encontrar un módulo compatible.

// Ejemplo de Package.swift\ndependencies: [\n    .package(url: "https://github.com/Alamofire/Alamofire.git", from: "5.6.0")\n]

Qué hacer:

\n
• Ve a File → Packages → Update to Latest Package Versions
\n
• Si el problema persiste — elimina el framework y agrégalo de nuevo
\n
• Verifica Package Dependencies en el proyecto — el módulo debe estar en verde
\n

4. Conflicto de arquitecturas (Architectures)

Los frameworks antiguos pueden estar compilados solo para arm64, mientras que tu proyecto incluye el simulador (x86_64). Con la llegada de Apple Silicon, esto se ha convertido en una causa frecuente.

Solución: Añade en Build Settings → Excluded Architectures para la compilación Debug:

\n
• Para el simulador: arm64
\n
• Para el dispositivo: $(ARCHS_STANDARD)
\n

5. Ruta de búsqueda incorrecta (Framework Search Paths)

Si añades el framework manualmente, Xcode debe saber dónde buscarlo. Verifica Framework Search Paths:

\n
• Build Settings → Framework Search Paths
\n
• Asegúrate de que la ruta lleve a la carpeta con .framework o .xcframework
\n
• Para SPM normalmente no es necesario especificar nada, pero para frameworks manuales es obligatorio
\n

6. El framework no está añadido a todos los targets

En el proyecto puede haber varios targets (aplicación principal, widgets, extensiones). Si añadiste el módulo solo a uno, los otros targets no lo verán.

Verificación: Selecciona el framework en el Project Navigator → inspector derecho → Target Membership — marca todos los targets necesarios.

7. Problemas con CocoaPods (si lo usas)

CocoaPods es un clásico, pero a veces después de pod install el framework no se enlaza