Error al importar una solución de Copilot studio por falta de referencia de conexión: solución

Al importar una solución en Copilot Studio, el proceso puede fallar con un error sobre una referencia de conexión faltante. Esto ocurre porque la solución contiene referencias a conexiones que no existen en el entorno de destino. El error impide que la importación se complete y bloquea la canalización de implementación. Este artículo explica por qué ocurre el error y proporciona los pasos exactos para solucionarlo.

Por qué falla la importación de soluciones de Copilot Studio con una referencia de conexión faltante

Una solución de Copilot Studio es un paquete que contiene configuraciones de copiloto, flujos y conectores. Cuando exporta una solución de un entorno e la importa en otro, la solución espera que todas las referencias de conexión que usó en el entorno de origen existan en el entorno de destino. Una referencia de conexión vincula un conector a una instancia de conexión específica. Si el entorno de destino no tiene esa referencia de conexión, el proceso de importación no puede resolver el vínculo y falla con el error “Missing connection reference”.

La causa raíz es que las referencias de conexión son específicas del entorno. Están vinculadas al identificador de conexión y a la instancia de conexión creada en el entorno de origen. Cuando exporta la solución, la referencia de conexión se incluye, pero la instancia de conexión real no. El entorno de destino debe tener una referencia de conexión con el mismo nombre lógico y una instancia de conexión válida detrás de ella.

Este problema es común al mover soluciones entre entornos de desarrollo, prueba y producción. También ocurre cuando importa una solución de un inquilino diferente o de una solución administrada que se exportó sin incluir referencias de conexión.

Pasos para solucionar el error de referencia de conexión faltante

1. Identifique la referencia de conexión faltante
   Abra los detalles del error de importación. En Power Apps o Copilot Studio, vaya a Soluciones y seleccione la importación fallida. Haga clic en Ver registro. El registro muestra el nombre de la referencia de conexión faltante. Anote el nombre lógico exactamente como aparece.
2. Cree la referencia de conexión faltante en el entorno de destino
   En el entorno de destino, vaya a Power Apps > Soluciones. Abra la solución que falló. Seleccione Conexiones en la navegación izquierda. Haga clic en Nueva conexión y seleccione el tipo de conector que coincida con la referencia faltante. Por ejemplo, si la referencia faltante es para Microsoft Dataverse, cree una conexión de Dataverse. Después de crear la conexión, vuelva a la solución y agregue un componente de referencia de conexión. Establezca el nombre lógico para que coincida con la referencia faltante del registro. Seleccione la conexión que acaba de crear.
3. Vuelva a importar la solución
   Después de crear la referencia de conexión, intente la importación de nuevo. En Power Apps, seleccione Soluciones > Importar. Elija el archivo de solución. En la página de configuración de importación, asegúrese de que la referencia de conexión esté asignada correctamente. El sistema ahora debería mostrar la nueva referencia de conexión como disponible. Complete la importación.
4. Si la importación sigue fallando, use la herramienta Solution Packager
   Descargue e instale la CLI de Power Platform. Abra un símbolo del sistema y ejecute pac solution unpack --zipfile "path-to-solution.zip" --folder "path-to-output-folder". Esto desempaqueta la solución en archivos XML. Navegue a la carpeta y abra la carpeta Other. Busque el archivo XML que contiene la referencia de conexión. Edite el archivo para agregar la referencia de conexión faltante con el nombre lógico correcto. Luego vuelva a empaquetar la solución con pac solution pack --zipfile "path-to-new-solution.zip" --folder "path-to-output-folder". Importe la solución reempaquetada.
5. Verifique las variables de entorno
   Si la referencia de conexión usa variables de entorno, asegúrese de que esas variables existan en el entorno de destino. Vaya a Soluciones > Variables de entorno. Cree las variables faltantes con el mismo nombre de esquema y establezca valores predeterminados. Luego vuelva a importar la solución.

Si la importación sigue fallando después de crear la referencia de conexión

El nombre lógico de la referencia de conexión no coincide

El nombre lógico en el entorno de destino debe coincidir exactamente con el nombre lógico del entorno de origen. Incluso una diferencia de un solo carácter hace que la importación falle. Copie el nombre lógico del registro de importación y péguelo al crear la referencia de conexión. No lo escriba manualmente.

La instancia de conexión no es válida o ha expirado

Una referencia de conexión apunta a una instancia de conexión. Si la instancia de conexión ha expirado o se ha eliminado, la importación fallará. Después de crear una nueva conexión, verifique que esté en estado activo. Vaya a Datos > Conexiones en Power Apps y compruebe el estado. Si el estado muestra “Expired”, vuelva a autenticar la conexión.

La solución contiene varias referencias faltantes

El registro de importación puede mostrar solo la primera referencia faltante. Después de corregir esa, la siguiente importación puede fallar con una referencia faltante diferente. Repita el proceso para cada referencia faltante que aparezca en el registro. Para evitar esto, abra el XML de la solución y busque todos los elementos connection-reference. Cree todas las referencias faltantes antes de intentar la importación de nuevo.

La solución administrada no se puede modificar

Si está importando una solución administrada, no puede agregarle referencias de conexión directamente. En su lugar, cree las referencias de conexión en el entorno de destino antes de importar. La solución administrada las detectará automáticamente si los nombres lógicos coinciden. Si la solución administrada no las detecta, comuníquese con el editor de la solución para que proporcione una versión actualizada con las referencias de conexión incluidas.

Creación manual de referencias de conexión frente a importación automatizada

Elemento	Creación manual	Importación automatizada con referencias de conexión
Tiempo de configuración	Alto: requiere la creación manual de cada referencia	Bajo: las referencias se incluyen en la solución
Riesgo de error	Alto: las discrepancias de nombres lógicos son comunes	Bajo: los nombres están preconfigurados
Ideal para	Entornos de desarrollo y prueba	Producción y canalizaciones de CI/CD
Mantenimiento	Requiere actualizaciones manuales en cada importación	Se resuelve automáticamente durante la importación

Ahora puede solucionar el error de referencia de conexión faltante en las importaciones de soluciones de Copilot Studio creando las referencias de conexión necesarias o editando el XML de la solución. Antes de implementar en producción, verifique que todas las referencias de conexión estén presentes y que las variables de entorno estén definidas correctamente. Como sugerencia avanzada, use la CLI de Power Platform para automatizar la creación de referencias de conexión en varios entornos y reducir los errores manuales.