Solución de problemas de Capacitor iOS: errores comunes y soluciones

La mayoría de los problemas de iOS en Capacitor se agrupan en cinco categorías: toolchain incorrecta, resolución de dependencias (SPM o CocoaPods), errores de compilación de plugins, firma de code y problemas en tiempo de ejecución como “plugin is not implemented” o un WebView en blanco. Comienza con bunx cap doctor, confirma que tienes Xcode 26 seleccionado y ejecuta bunx cap sync ios, y lee el primer error en el log de compilación de Xcode, no el último.

Esta guía recoge los errores que vemos con más frecuencia en proyectos de Capacitor 8, qué causa cada uno y la solución. Para Android, consulta la guía de solución de problemas de Capacitor Android.

Checklist de triage rápido

Ejecuta esto antes de ponerte a buscar un error concreto:

bunx cap doctor            # Capacitor, CLI and plugin versions should match
node -v                    # 22 or later for Capacitor 8
xcodebuild -version        # 26.x
xcode-select -p            # should point to the Xcode you expect
bun run build && bunx cap sync ios

• Versiones: @capacitor/core, @capacitor/ios y @capacitor/cli must share the same major. Mismatches cause odd compile and runtime errors. See fix Capacitor version mismatch errors.
• Un solo Xcode: si tienes varias versiones de Xcode, xcode-select -p determina cuál usa CLI. Corrígelo con sudo xcode-select -s /Applications/Xcode.app.
• Qué gestor de paquetes: si ios/App/CapApp-SPM existe, el proyecto usa SPM. Si ios/App/Podfile existe, usa CocoaPods.

Errores de toolchain

Xcode o SDK muy antiguos

Síntomas: value of type 'WKWebView' has no member 'isInspectable', errores de sintaxis de Swift en Capacitor, o compiling for iOS 15.0, but module 'X' has a minimum deployment target of iOS 16.0.

Capacitor 8 requiere Xcode 26. En GitHub Actions, macos-latest no siempre apunta a la imagen con la versión más reciente de Xcode. Fija una imagen que incluya Xcode 26 y selecciónala explícitamente:

- run: sudo xcode-select -s /Applications/Xcode_26.0.app

Consulta la documentación de la imagen del runner para la ruta exacta. Para el error de módulo mínimo, sube el deployment target de tu app al mínimo del plugin, o usa una versión anterior del plugin.

ITMS-90725: SDK version issue al subir

La compilación se realizó con un SDK más antiguo que el que Apple acepta actualmente. Desde el 28 de abril de 2026, las subidas deben compilarse con Xcode 26 y el SDK de iOS 26. Ver Requisito de Xcode 26 de Apple para apps de Capacitor. Build de Capgo ya compila con Xcode 26 si no quieres mantener runners de Mac.

Errores de Swift Package Manager

Missing package product 'CapApp-SPM'

Xcode no ha resuelto el paquete local, o su caché está desactualizada.

1. Archivo > Paquetes > Restablecer caché de paquetes.
2. Archivo > Paquetes > Resolver versiones de paquetes.
3. Si la app se migró desde CocoaPods, comprueba que CapApp-SPM se haya añadido en las Package Dependencies del proyecto pestaña y está vinculada al target de la App.

product 'X' required by package 'capapp-spm' target 'CapApp-SPM' not found

De un plugin Package.swift usa un nombre de paquete o producto que no coincide con el que Capacitor CLI generó a partir de su nombre npm. Esto es un bug del plugin. Actualiza el plugin, o corrígelo. Los autores de plugins pueden ver la regla de nombrado en migrar un plugin de Capacitor a SPM.

“Algunos plugins de Capacitor instalados no son compatibles con SPM”

Esta advertencia durante cap sync significa que al menos un plugin no tiene Package.swift. Se excluye de la app, por lo que las llamadas fallan con “not implemented”. Actualiza el plugin, cámbialo por uno que soporte SPM, o usa CocoaPods por ahora.

Identidad de paquete o nombre de target duplicados

Dos plugins comparten la misma identidad de paquete o nombre de target (a menudo un nombre genérico como Plugin). Desde CLI 8.4 puedes solucionarlo desde la config de Capacitor:

const config: CapacitorConfig = {
  // ...
  experimental: {
    ios: {
      spm: {
        packageOptions: {
          '@acme/capacitor-foo': { symlink: true },
          '@acme/capacitor-bar': { moduleAliases: { Plugin: 'AcmeBarPlugin' } },
        },
      },
    },
  },
};

symlink hace que CLI referencie el plugin mediante una carpeta symlink con una ruta única. moduleAliases renombra un módulo en conflicto para esa dependencia. Reporta también el conflicto upstream.

No edites CapApp-SPM/Package.swift

CLI lo sobrescribe en cada sync. Los cambios locales se pierden. Usa las experimental.ios.spm opciones de configuración en su lugar.

Errores de CocoaPods

No such module 'Capacitor'

Abriste App.xcodeproj en lugar de App.xcworkspace. Usa bunx cap open ios. Si el workspace está abierto y el error persiste, ejecuta bunx cap sync ios para reinstalar los pods.

CocoaPods could not find compatible versions for pod "X"

Dos causas:

1. Repositorio de specs obsoleto: ejecuta cd ios/App && pod install --repo-update.
2. Pins en conflicto: dos plugins necesitan versiones incompatibles del mismo pod. El error muestra la cadena. Actualiza el plugin con el pin estricto, alinea las versiones (para Firebase, mantén todos los plugins de Firebase en la misma versión de SDK) o corrige el podspec.

Si sigue fallando, elimina ios/App/Podfile.lock y ios/App/Pods, y luego sincroniza de nuevo. Esto también actualiza todos los pods, así que prueba después.

The sandbox is not in sync with the Podfile.lock

Ejecuta bunx cap sync ios. Suele ocurrir tras cambiar de rama o con instalaciones parciales.

Unable to find compatibility version string for object version '70'

Tu project.pbxproj usa un formato que tu versión de CocoaPods no puede leer. Actualiza CocoaPods (brew upgrade cocoapods o súbelo en tu Gemfile). Como último recurso, haz una copia de seguridad del archivo y baja objectVersion.

Sandbox: rsync(...) deny(1) file-write-create

El sandbox de scripts de usuario de Xcode bloquea el script de embebido de frameworks de CocoaPods. Configura Build Settings > User Script Sandboxing a No en el target de la App.

could not find module 'Capacitor' for target 'x86_64-apple-ios-simulator'

La compilación del simulador se está ejecutando para Intel. En Apple Silicon, esto suele significar que Xcode se ejecuta bajo Rosetta o una versión EXCLUDED_ARCHS[sdk=iphonesimulator*] = arm64 la configuración es un residuo de una solución temporal pasada. Ejecuta Xcode de forma nativa, elimina esa configuración del target de la App y de cualquier post_install hook, y luego limpia y vuelve a compilar.

Errores de compilación

Command PhaseScriptExecution failed with a nonzero exit code

Es un wrapper. Expande la fase de build que falla en el Report navigator y lee la salida del script. Causas comunes en apps de Capacitor:

• Un Run Script necesita node y Xcode no lo encuentra, porque Xcode no carga tu perfil de shell y Node está instalado con nvm, fnm o Volta. Usa la ruta completa a node en el script, o exporta PATH al inicio del mismo.
• Un script de carga de informes de errores (Sentry, Crashlytics) no tiene credenciales en CI.
• El script de embebido de CocoaPods está bloqueado por el sandbox de scripts de usuario (ver arriba).

'X' is only available in iOS 16.0 or newer

Un plugin usa un API superior a tu objetivo de despliegue. Aumenta el objetivo en Xcode, en el Podfile (platform :ios, '16.0') si usas CocoaPods, y consulta el README del plugin para su mínimo.

Errores de concurrencia de Swift 6 en un plugin

Mensajes como Sending 'x' risks causing data races aparecen cuando un plugin o el target de tu app usa el modo de lenguaje Swift 6. Capacitor 8 no admite oficialmente Swift 6. Mantén el target de la App en modo de lenguaje Swift 5 hasta que el plugin se actualice.

Firma de Code

Signing for "App" requires a development team

Abrir Target de la App > Firmado y Capacidades y selecciona un equipo. En CI, pasa DEVELOPMENT_TEAM a xcodebuild o usa una herramienta de firma. Si el error menciona un bundle de recursos de un pod en lugar de App, desactiva la firma para los targets de bundle en el Podfile post_install hook.

Provisioning profile "X" doesn't include the ... entitlement

Añadiste una capacidad (Notificaciones Push, Dominios Asociados, Iniciar sesión con Apple) sin regenerar el perfil. Actívala en el App ID en el portal de Apple Developer y luego actualiza los perfiles. Nuestro generador de certificados iOS ayuda a crear certificados sin la complicación de la llave de Mac, y Buscador de UDID ayuda a registrar dispositivos de prueba.

Unable to install "App" en el dispositivo

Activa el Modo Desarrollador en el dispositivo (Ajustes > Privacidad y seguridad > Modo desarrollador), confía en el certificado del desarrollador y asegúrate de que el UDID del dispositivo esté en el perfil de aprovisionamiento para builds de desarrollo.

Errores en tiempo de ejecución

"X" plugin is not implemented on ios

El lado de JavaScript no encontró ninguna implementación nativa. Revisa en este orden:

1. El plugin está en package.json y ejecutaste bunx cap sync ios después de instalarlo.
2. Para SPM: el plugin aparece en ios/App/CapApp-SPM/Package.swift. Si no, no tiene Package.swift.
3. Para CocoaPods: el plugin aparece en el capacitor_pods bloque del Podfile y pod install no emitió advertencias.
4. No tienes dos plugins registrando el mismo nombre de JS (por ejemplo, dos plugins de notificaciones push).
5. WKAppBoundDomains no está en Info.plist, o si lo está, limitsNavigationsToAppBoundDomains está configurado y localhost is listed. App-bound domains block plugin script injection otherwise.
6. Limpia la carpeta de build y vuelve a compilar. Las builds obsoletas conservan registros antiguos de plugins.

Pantalla en blanco al iniciar

Inspecciona el WebView con Safari Web Inspector primero. La mayoría de las pantallas en blanco son un error de JavaScript.

• Incorrecto webDir: capacitor.config.ts apunta a una carpeta que no contiene index.html. Revisa ios/App/App/public.
• Build target demasiado nuevo: tu bundler genera sintaxis que WebKit no soporta. iOS 15 es el mínimo para Capacitor 8, así que apunta a safari15 o superior en Vite/esbuild y revisa tus browserslist.
• Rutas de assets absolutas: una base configurada a un CDN o subpath en tu bundler rompe la carga local.
• Live reload inaccesible: el dev server debe escuchar en tu IP de LAN (--host 0.0.0.0), el teléfono debe estar en la misma red y la app necesita el Local Network permisos (Ajustes > Privacidad y seguridad > Red local). Eliminar server.url de la config antes de los builds de release.
• Bundle de Live update roto: si la app usa actualizaciones OTA, un bundle defectuoso puede dejar la pantalla en blanco. El actualizador de Capgo revierte automáticamente cuando notifyAppReady() no se llama a tiempo. Consulta la docs del updater.

Contenido bajo la muesca o el indicador de inicio

Añadir viewport-fit=cover a tu meta tag de viewport y añade padding con env(safe-area-inset-top) y env(safe-area-inset-bottom). El plugin System Bars de Capacitor 8 controla el estilo y la visibilidad de la barra de estado en ambas plataformas.

El teclado cubre las entradas

Configurar el Plugin de teclado resize modo (native, body, ionic o none) y prueba en un dispositivo real. Los simuladores manejan el teclado de forma diferente.

Errores de App Store Connect

• ITMS-91053: Missing API declaration: tu app o un plugin usa un API requerido sin una entrada en el manifiesto de privacidad. Añade un PrivacyInfo.xcprivacy al objetivo de la app con las razones, y actualiza los plugins que incluyen su propio manifiesto.
• ITMS-90725: SDK version issue: recompila con Xcode 26.
• Invalid Bundle. The bundle ... contains disallowed file 'Frameworks': un framework está incrustado dentro de una extensión u otro framework. Revisa Embed ajustes para extensiones de la app.

Cómo depurar cuando el error no aparece en la lista

1. Inspector web de Safari para errores de JS y llamadas de red. Las builds de debug son inspeccionables en iOS 16.4+. Para builds de release, configura ios.webContentsDebuggingEnabled: true temporalmente.
2. consola de Xcode para logs nativos, incluidos los de Capacitor ⚡️ mensajes del bridge que muestran cada llamada de plugin.
3. Console.app con el dispositivo seleccionado para logs de crash y del sistema.
4. Aislar: crea una app nueva con bun create @capacitor/app, añade solo el plugin sospechoso y comprueba si el error se reproduce.

El guía definitiva para depurar apps Capacitor profundiza en cada herramienta. Si la causa raíz es un error de un plugin, un parche suele ser la forma más rápida de desbloquear mientras esperas un release.