Errores de código personalizado en FlutterFlow y cómo resolverlos

La mayoría de los errores de código personalizado en FlutterFlow salen de una lista corta: el nombre en el código no coincide con el del editor, un argumento está definido distinto en los ajustes y en el código, a un paquete le falta el import o choca con otro paquete, o un valor tiene el tipo equivocado o puede ser nulo. El botón Compile Code y el analizador de código de FlutterFlow muestran dónde está el error; regenerar el código base (boilerplate) y compararlo con el tuyo resuelve buena parte de los casos.

En esta guía vemos en qué se diferencian los tipos de código personalizado, recorremos los errores comunes según el síntoma y cerramos con hábitos para que el código personalizado no rompa el build completo.

¿Qué tipos de código personalizado tiene FlutterFlow?

Cada tipo tiene sus reglas, y muchos errores vienen de tratar uno como si fuera otro:

Dos reglas para recordar: las Custom Functions tienen que compilar para que la app funcione, y los Custom Widgets necesitan ancho y alto definidos, o no se van a mostrar bien.

¿Cómo encuentro el error real?

1. Abre el elemento de código personalizado y haz clic en Compile Code. El analizador se detiene en el primer error de compilación y lo muestra.
2. Lee el primer error: los siguientes suelen ser consecuencia de él.
3. Revisa los avisos del proyecto en FlutterFlow sobre widgets o acciones sin compilar.
4. Para errores que solo aparecen con la app corriendo, usa la consola del navegador en Run mode o el panel Debug Info en Test mode.

Si el mensaje dentro de FlutterFlow es vago, descarga el código y córrelo en tu computadora con las herramientas de Flutter, o usa la extensión de FlutterFlow para VS Code. El compilador local casi siempre indica el archivo y la línea exactos.

"Unknown error compiling custom code": ¿qué significa?

Los usuarios de FlutterFlow reportan seguido un mensaje genérico que dice que una causa común es un custom widget o una custom action cuyo nombre en el código no coincide con el del editor. Tómalo al pie de la letra primero:

• El nombre de la función de una Custom Action debe ser igual al nombre de la acción en FlutterFlow.
• El nombre de la clase de un Custom Widget debe ser igual al nombre del widget en FlutterFlow.

Lo más rápido es Add Boilerplate Code, que genera el código con los nombres y argumentos correctos. Compáralo con el tuyo. En la app de escritorio, regenerar puede reemplazar todo el archivo, así que copia tu código en un lugar seguro antes.

Si los nombres coinciden y el error sigue, sigue leyendo.

¿Por qué FlutterFlow dice que un argumento o un tipo no coincide?

Los argumentos que defines en el panel de ajustes y los parámetros del código tienen que ser idénticos: mismos nombres, mismos tipos, mismo orden y la misma posibilidad de ser nulos. Si un argumento es opcional (nullable) en los ajustes, decláralo nullable también en el código (por ejemplo String? note) y maneja el caso nulo.

Otras causas de la lista de FlutterFlow para custom actions:

• Tipo de retorno distinto. La función debe devolver exactamente el tipo configurado en el panel de ajustes.
• Nombres repetidos. Una acción y uno de sus argumentos no pueden llamarse igual.
• Palabras reservadas como nombre. Palabras clave de Dart como in, as, enum, import, this o static no sirven como nombre de argumento.
• Un valor o una lista. Pasar un solo elemento donde se espera una lista, o al revés.
• Conversiones de tipo. Un campo de texto que dice "42" no es un int. Convierte de forma explícita con int.tryParse, .toString() o .toDouble().
• Tipos duplicados. No vuelvas a definir un tipo de dato que ya existe en el panel de esquema. FlutterFlow genera tus tipos personalizados como clases con nombres del estilo ItemsStruct; usa esas.
• Tipos en los callbacks. Una acción de callback que pasas a un widget debe devolver el tipo que el widget espera.

¿Por qué falla el import de un paquete?

Falta el import o está en el lugar equivocado

FlutterFlow agrega imports estándar a cada acción y widget nuevo, y esos no se pueden editar. Los tuyos van después de la línea que dice "Do not remove or modify the code above". Si ves algo como "The method 'AnimatedText' isn't defined", el paquete está instalado pero no importado. Copia la línea exacta del import desde la pestaña Installing del paquete en pub.dev.

Las Custom Functions no admiten imports adicionales. Si necesitas un paquete, conviértela en una Custom Action.

El paquete no está declarado o su versión choca

Agrega el paquete en Settings and Integrations, Project Dependencies, Custom Dependencies, con Add Pub Dependency, y súmalo en la sección Pubspec Dependency del archivo de código. FlutterFlow muestra los conflictos de versiones como avisos en la pestaña Custom Dependencies y en el editor de código.

Los conflictos aparecen cuando tu paquete necesita otra versión de algo que FlutterFlow ya usa, o cuando dos de tus paquetes no se ponen de acuerdo. Revisa las dependencias del paquete en pub.dev, prueba una versión compatible con lo que trae FlutterFlow y agrega los paquetes de a uno, compilando después de cada uno, para saber cuál rompió el build. Algunos paquetes necesitan que importes otros paquetes también; la página de pub.dev los lista.

Funciona en el celular pero no en Run o Test mode

Run y Test mode ejecutan tu app en la web. La documentación de FlutterFlow indica que un paquete debe ser compatible con Web para funcionar ahí. La cámara, Bluetooth y algunos paquetes de archivos no lo son. Pruébalos en un dispositivo.

¿Cómo evito que un archivo roto bloquee toda la app?

Los Custom Widgets y las Custom Actions tienen la opción Exclude from compilation. Al activarla, el resto del proyecto compila mientras arreglas ese elemento. La documentación de FlutterFlow también la recomienda para código que importa archivos internos de FlutterFlow (rutas como ../../flutterflow). Acuérdate de desactivarla y compilar cuando termines, o vas a publicar sin que ese código se haya revisado.

¿Cómo evito que el código personalizado se vuelva a romper?

1. Parte siempre del boilerplate y después agrega tu lógica.
2. Usa nombres de widget distintivos. Un widget llamado Map o Widget puede chocar con un paquete.
3. Mantén el código personalizado chico. Pon la lógica compleja en una acción bien probada en vez de repartirla en muchas.
4. Maneja los nulos a propósito. Dale un valor de respaldo a cada entrada que pueda ser nula.
5. Anota para qué está cada paquete, así es fácil decidir cuál quitar cuando chocan las versiones.
6. Usa una rama para los cambios grandes. FlutterFlow advierte que pasar a su nuevo diseño de código personalizado no tiene vuelta atrás, así que pruébalo antes en una rama.

Para ver el panorama de lo que suele romperse en código generado, revisa nuestra guía sobre errores de TypeScript y builds que fallan, y la de cómo reportar un error a un desarrollador para conseguir ayuda más rápido.

Respuestas rápidas

¿Por qué mi custom widget de FlutterFlow no aparece en el editor? Los Custom Widgets tienen que compilar bien antes de mostrarse en la vista previa, y necesitan ancho y alto definidos.

¿Por qué no puedo importar un paquete en una Custom Function? Las Custom Functions no permiten imports adicionales. Usa una Custom Action o un Custom Widget.

¿Qué hace Exclude from compilation? Salta ese widget o acción al compilar para que el resto del proyecto pueda construirse. Desactívalo cuando lo arregles.

¿Por qué mi paquete funciona en el celular pero no en Test mode? Test y Run mode corren en la web, y el paquete tiene que ser compatible con Web.

¿Sigues trabado con un error de compilación?

Algunos errores solo se entienden mirando el proyecto completo. Nuestro servicio para arreglar apps de FlutterFlow puede encargarse del código personalizado, los conflictos de paquetes y los builds, y cuando la app esté lista te ayudamos a publicarla en la App Store. Mándanos el mensaje de error exacto por el formulario de contacto.