Resolución de problemas
Esta guía está ordenada por lo que ves en pantalla. Cada apartado explica qué ves, por qué pasa y qué hacer.
Dónde mirar primero
Casi todos los problemas se aclaran en uno de estos tres sitios:
- El propio componente. Un borde amarillo indica que le falta un campo obligatorio. Un triángulo rojo indica que falló en la última ejecución: pasa el ratón por encima para leer el motivo.
- Ejecuciones, a la izquierda del Entorno de Pruebas. Lista los pasos de la última prueba y lo que recibió y devolvió cada componente.
- Reg. de Ejecuciones, en el menú lateral. Guarda todas las ejecuciones, también las que llegan de otras aplicaciones y del Programador. Pulsa Ver en una ejecución y selecciona el paso del componente que falló: en Salida, el texto de
errorMessageexplica el error. Ver Registro de ejecuciones.
El flujo no se ejecuta
Aparece «¡Ups! Parece que te olvidaste de algo»
Qué ves. Al probar el flujo aparece el aviso ¡Ups! Parece que te olvidaste de algo con una lista de componentes y campos, por ejemplo Gemini is missing Credential. Los componentes afectados tienen el borde amarillo.
Por qué pasa. A esos componentes les falta un campo obligatorio. NappAI no ejecuta el flujo hasta que estén completos.
Qué hacer. Abre cada componente de la lista y rellena el campo indicado. Si es Credential, elige una credencial o crea una con Crear nueva credencial. Algunos campos solo aparecen con ciertas operaciones: si cambias la Operation de un componente, revisa de nuevo sus campos.
Aparece «Error al construir flujo»
Qué ves. El aviso Error al construir flujo con un mensaje debajo.
Por qué pasa. El flujo no se pudo poner en marcha. El mensaje de debajo dice el motivo.
Qué hacer. Lee el mensaje. Si habla de un perfil de ejecución o de demasiadas ejecuciones, consulta Un perfil de ejecución rechaza la ejecución. Si no, revisa que las conexiones del flujo sean correctas y vuelve a probar.
Un componente no llega a ejecutarse
Qué ves. El flujo termina, pero un componente no muestra ni marca verde ni triángulo rojo, y no aparece en Ejecuciones.
Por qué pasa. El flujo no llegó a él. Lo normal es que un componente anterior lo haya desviado, por ejemplo un Conditional Router cuya condición no se cumplió, o que un componente anterior no devolviera nada.
Qué hacer. En Ejecuciones, revisa la salida del último componente que sí se ejecutó. Comprueba que devuelve lo que espera el siguiente; en un Conditional Router, que el texto coincida con Match Text.
Un componente muestra un error
Qué ves. El componente tiene un triángulo rojo y la ejecución aparece como fallida.
Por qué pasa. El componente recibió algo que no esperaba, el servicio externo rechazó la petición o el servicio no respondió. El motivo exacto está en el mensaje de error.
Qué hacer.
- Pasa el ratón por encima del triángulo rojo, o abre la ejecución y selecciona el paso del componente, para leer el error.
- Revisa en Entrada lo que recibió. Muchos errores se deben a que el componente anterior devolvió algo vacío o con otra forma.
- Si el error viene del servicio externo, comprueba la credencial (siguiente apartado) y los datos que envías: un identificador que no existe, un modelo que no está disponible o un campo con un formato que el servicio no acepta.
- Corrige y vuelve a ejecutar. Con el botón de play del componente ejecutas el flujo solo hasta ese punto.
Una credencial falla
El servicio rechaza el acceso
Qué ves. El componente que usa la credencial falla y su error indica que el servicio no acepta la clave o el acceso.
Por qué pasa. La clave se ha anulado o ha caducado en el servicio, se escribió mal, o la cuenta no tiene permiso para lo que pide el componente. En los servicios con inicio de sesión, como Google, el acceso también caduca si cambias la contraseña o retiras el permiso desde tu cuenta.
Qué hacer.
- Para una clave: edita la credencial en Credenciales, vuelve a escribir la clave y pulsa Actualizar. Los valores secretos no se muestran, así que hay que escribirlos de nuevo.
- Para un servicio con inicio de sesión: edita la credencial y pulsa Revalidar para entrar otra vez.
- Si el componente necesita escribir y la credencial se creó con acceso de solo lectura, crea otra credencial con el acceso adecuado.
Ver Credenciales.
Funciona en pruebas y falla en producción, o al revés
Por qué pasa. La credencial puede tener valores distintos según el entorno, y la versión desplegada se ejecuta con el entorno que se guardó al crearla.
Qué hacer. Edita la credencial y revisa la sección Entornos. Comprueba con qué entorno se creó la versión desplegada en Historial de Versiones. Ver Entornos.
Un componente se ha quedado sin credencial
Qué ves. Un componente que funcionaba aparece con el borde amarillo.
Por qué pasa. Se borró la credencial que usaba, o el flujo se importó desde otra cuenta.
Qué hacer. Elige otra credencial en su campo Credential.
No se puede guardar la credencial
Si al crearla ves Error: El nombre debe ser único, ya tienes otra credencial del mismo servicio con ese nombre. Elige otro.
El playground no responde como esperas
No hay campo para escribir
Por qué pasa. El flujo no tiene un Chat Input. En ese caso el playground muestra un formulario con las entradas del flujo y el botón Ejecutar Flujo.
Qué hacer. Rellena el formulario y pulsa Ejecutar Flujo, o añade un Chat Input si quieres probarlo como un chat.
Se queda en «Construyendo…» mucho tiempo
Por qué pasa. Algún componente está tardando: un modelo de lenguaje con mucho texto, un agente que usa varias herramientas seguidas o un servicio externo lento.
Qué hacer. Mira en Ejecuciones qué paso está en marcha. Si el flujo tiene un perfil de ejecución con tiempo máximo, la ejecución se detiene al superarlo.
El botón para probar está desactivado
Por qué pasa. Tu rol no permite probar flujos, o el flujo se compartió contigo con el nivel Puede ver. Al pasar el ratón por encima verás Tu rol no permite hacer esto (probar flujos).
Qué hacer. Ver Te falta un permiso.
Aparece «Stream connection failed»
Qué ves. Un aviso Error con el texto Stream connection failed.
Por qué pasa. Se cortó la conexión entre tu navegador y la ejecución, por ejemplo por un corte de red.
Qué hacer. Comprueba tu conexión, recarga la página y vuelve a probar. El resultado de la ejecución, si terminó, está en Reg. de Ejecuciones.
El flujo empieza con Telegram, WhatsApp u otra aplicación
Por qué pasa. Los mensajes de esas aplicaciones llegan a la versión publicada del flujo, no al playground.
Qué hacer. Despliega una versión y conecta la aplicación desde la pestaña correspondiente de Acceso a API. Ver Versiones y publicación.
Para el playground de un agente de voz, ver Solución de problemas del agente de voz.
El agente no responde como esperas
No usa la herramienta correcta
Por qué pasa. El agente elige la herramienta por su descripción. Si es vaga o se parece a la de otra herramienta, puede equivocarse.
Qué hacer. En la pestaña Avanzado de cada herramienta, escribe en Tool Description qué hace, qué necesita y qué no puede hacer. Por ejemplo: Lee los productos de la tabla Productos. No puede crear ni borrar registros.
La herramienta recibe valores fijos o vacíos
Por qué pasa. Solo los campos marcados como Definido por IA los rellena el agente. El resto usa siempre el valor escrito en el componente.
Qué hacer. En el componente de la herramienta, pulsa el botón con destellos de cada campo que deba decidir el agente.
Inventa datos o no sigue el formato
Qué hacer. Haz más concreto el System Prompt: di qué debe hacer, de dónde debe sacar la información (por ejemplo, responde solo con lo que devuelvan tus herramientas) y qué hacer si no la encuentra. Si necesitas una respuesta con una forma fija, describe esa forma con un ejemplo.
Hace demasiadas cosas a la vez
Qué hacer. Si un agente tiene muchas herramientas o instrucciones muy largas, reparte el trabajo: un agente que clasifica la petición y varios agentes especializados, cada uno con pocas herramientas. El caso de uso de atención al cliente muestra cómo.
Un flujo publicado devuelve un error
El flujo no tiene versión desplegada
Qué ves. En Acceso a API, en modo Producción, aparece el botón Desplegar una versión. En el Programador no se puede guardar la programación.
Qué hacer. Despliega una versión. Ver Versiones y publicación.
La llamada responde con el código 401
Por qué pasa. La llamada no lleva la clave API o la clave no es válida, por ejemplo porque se regeneró su secreto o se borró.
Qué hacer. Copia el código de nuevo desde Acceso a API con la clave correcta, o actualiza el secreto en la aplicación que llama. Ver Claves API.
Los cambios no se notan en producción
Por qué pasa. Has cambiado el borrador. Las llamadas en producción usan la versión desplegada.
Qué hacer. Crea una versión nueva con los cambios y despliégala.
La llamada funciona pero el resultado está mal
Qué hacer. Busca la ejecución en Reg. de Ejecuciones, filtrando por el flujo y la fecha, y revisa paso a paso qué hizo cada componente.
Un perfil de ejecución rechaza la ejecución
«Ejecución bloqueada por el perfil de ejecución»
Qué ves. El aviso Ejecución bloqueada por el perfil de ejecución, con el nombre del perfil y el componente o el modelo que no está permitido. Desde otra aplicación, la llamada falla con ese mismo motivo.
Por qué pasa. El flujo contiene un componente que su perfil bloquea, o usa un modelo que el perfil no permite. Pasa también al probarlo en el playground.
Qué hacer. Quita del flujo ese componente o cambia el modelo por uno permitido. Si el flujo necesita lo que el perfil bloquea, pide a quien gestiona los perfiles que cambie el perfil o le asigne otro.
«Demasiadas ejecuciones (429)»
Qué ves. El aviso Demasiadas ejecuciones (429): Este flujo se ha ejecutado demasiadas veces en el último minuto. Espera un momento y vuelve a intentarlo. Desde otra aplicación, la llamada responde con el código 429.
Por qué pasa. El flujo ha llegado al máximo de Ejecuciones por minuto de su perfil.
Qué hacer. Espera a que pase el minuto. Si el límite se queda corto, pide que se suba.
La ejecución se detiene antes de terminar
Por qué pasa. Ha superado el Tiempo máximo de ejecución de su perfil. La ejecución termina con error.
Qué hacer. Revisa en Reg. de Ejecuciones qué paso tarda más y simplifícalo, o pide que se amplíe el tiempo máximo.
Te falta un permiso
Un botón aparece desactivado
Qué ves. Al pasar el ratón por encima: Tu rol no permite hacer esto (…), con el permiso que falta, por ejemplo gestionar credenciales.
Por qué pasa. Tu rol en el equipo no incluye esa acción.
Qué hacer. Pide al propietario de la cuenta que te cambie el rol. Ver Roles y permisos.
No puedes abrir una página
Qué ves. No puedes abrir esta página y Tu rol no te permite (…). Pídeselo al dueño de la cuenta si lo necesitas.
Qué hacer. Igual que en el caso anterior: el propietario puede cambiarte el rol.
Aparece «No tienes permiso para hacer esto»
Qué ves. Un aviso No tienes permiso para hacer esto después de intentar una acción.
Por qué pasa. La acción necesita un permiso que tu rol no tiene, o el flujo se compartió contigo con un nivel que no la incluye.
Qué hacer. Si el flujo es de otra persona, pídele que te lo comparta con un nivel más alto. Ver Compartir un flujo. Si es de tu cuenta, pide al propietario que te cambie el rol.
Al importar un proyecto aparece «Error al cargar archivo»
Por qué pasa. El archivo no es un proyecto exportado desde NappAI o está dañado.
Qué hacer. Exporta el proyecto de nuevo desde su cuenta de origen con Exportar e impórtalo otra vez. Ver Proyectos.
Si sigues sin resolverlo
Escribe al equipo de NappAI desde Contáctanos, en el menú de tu usuario. Incluye el nombre del flujo, la fecha y la hora de la ejecución y el mensaje de error copiado desde Salida.