Depuración de Ultrafast: qué hacer si no conecta, no hace clic o se desvía
Si algo sale mal al ejecutar Jev Ultrafast, lo más probable es que se atasque en una de cuatro capas: el servicio local no arrancó, Chrome no conectó, la llamada al modelo fue rechazada, o la ejecución de la decisión chocó con un muro. Esta lección repasa los errores comunes de jev-ultrafast uno por uno según su «texto original», con causa y solución: primero una verificación rápida de 60 segundos, y luego identifica el tuyo.
Todos los textos originales de los errores provienen del código fuente del repositorio (jev_ultrafast/model.py, agent.py, browser.py, demo.py y la interfaz del inspector), se pueden buscar palabra por palabra y copiar para preguntar. No importa si te atascaste en un curso previo: si algo falló en instalación y ejecución, puedes volver aquí a consultarlo.
Qué podrás hacer al terminar
- Localizar en 60 segundos, con 4 comandos, cuál eslabón falló: directorio, Key, Chrome o capa de ejecución del navegador
- Identificar cada error de jev-ultrafast: texto original → causa → pasos de reparación
- Distinguir el tratamiento de tres tipos de errores: tipo stale (autocorrección en modo automático), tipo reintento (retroceso automático del código) y tipo manual (requiere que cambies la configuración o el objetivo)
- Entender las 6 visualizaciones de la barra de estado del inspector y saber qué hacer a continuación con done y blocked
- Recordar la lista de no soportados: shadow DOM, frames, canvas, subidas, ventanas emergentes nuevas, scroll anidado y componentes de teclado arbitrarios
- Usar Export trace para exportar la evidencia de decisiones y preguntar con la información mínima
Tu situación actual
- Pulsas Start demo y no pasa nada; no sabes si el servicio no arrancó, Chrome no conectó o falta la Key
- El error en inglés del recuadro rojo aparece un instante y desaparece; no sabes qué frase buscar y, si encuentras algo, no entiendes de qué capa es la culpa
- El estado del agent cambia a done / blocked, pero la página no muestra el resultado esperado: ¿el objetivo está mal escrito o esta página simplemente no se puede ejecutar?
Cuándo usar esta técnica
Cuando necesitas:
- Reparar errores atascados en Instalación y ejecución de Ultrafast, Completar Google Flights, Escribe tus propias tareas de navegador
- Evaluar antes de empezar si un sitio web es apto para Ultrafast: filtra primero con la lista de no soportados, no fuerces la entrada
Y no quieres:
- Borrar el repositorio y reinstalar al primer error, repitiendo todo el proceso de instalación desde cero
- No distinguir entre «la página cambió, hay que reintentar» y «la configuración está rota, hay que repararla», y perder medio día cambiando cosas sin sentido
🎒 Preparativos antes de empezar
- Haber completado Instalación y ejecución de Ultrafast (no importa si te atascaste, esta lección es justamente para desatascarte)
- Tener el repositorio clonado localmente y poder ejecutar comandos en el directorio raíz
jev-ultrafast/desde la terminal - (Opcional) Haber hecho Escribe tus propias tareas de navegador: los errores que surjan al usar la librería Agent también se pueden identificar aquí
Idea central
Primero determina la capa, luego mira el error. Una tarea Ultrafast atraviesa cuatro capas, y los errores de cada capa se ven distintos:
| Capa | Qué se comprueba | Error típico / síntoma |
|---|---|---|
| 1. Servicio local | Si uv run jev arrancó, si el directorio es correcto, si la dirección es 127.0.0.1 | Cannot reach local demo server / Forbidden |
| 2. Conexión de Chrome | Browser Harness, autorización de depuración remota | El panel no se mueve |
| 3. Llamada al modelo | Las dos Key, la red, la cuota | TYPE_TEXT needs TEXT_MODEL_API_KEY / Model provider returned HTTP 401 |
| 4. Decisión y ejecución | Cambios de página, presupuesto de acciones, límites de controles de la página | Target changed or is covered / el estado cambia a blocked |
Tres tipos de errores, tres tratamientos. Al ver un error, clasifícalo primero; no te apresures a actuar:
| Tipo | Ejemplo | Lo que debes hacer |
|---|---|---|
| De autocuración (stale, la página cambió) | Page changed since the decision / Target changed or is covered | No hay que hacer nada: la ejecución automática volverá a observar y decidir; en modo manual, pulsa una vez Choose next |
| De reintento (el servidor rechaza temporalmente) | 429 / 529 / 503 → el código lo intenta en total 3 veces (reintenta 2 veces) y, si sigue fallando, reporta Model provider returned HTTP 429/529/503 | Espera un poco y vuelve a ejecutar; revisa la cuota |
| Que requieren acción (configuración / presupuesto / límites) | Falta la Key, HTTP 401, 60 acciones de presupuesto, shadow DOM no soportado | Cambia la configuración, el objetivo o la página según los puntos siguientes |
💡 Tabla de referencia de la barra de estado del inspector (texto original de app.js)
| Muestra la barra de estado | Significado | Qué debes hacer |
|---|---|---|
| Ready to explore | Todavía no has pulsado Start demo | Rellena el objetivo y pulsa Start demo |
| Page observed · ready for a decision | Página observada, esperando decisión | Pulsa Choose next o Run automatically |
| Choice ready · inspect or execute | Decisión lista, pendiente de ejecutar | Revisa las probabilidades y pulsa Execute choice |
| Jev reports complete · inspect the page | El modelo eligió DONE | Verifica la página personalmente—DONE no es prueba de éxito |
| Stopped · no supported next action | blocked: acciones inválidas consecutivas o el modelo eligió BLOCKED | Mira los últimos pasos del Decision trail y compáralos con la lista de no soportados |
| Paused · needs attention | Pausado por error | Mira el texto del error en el recuadro rojo y encuéntrale su caso |
Primera revisión: verificación rápida en 60 segundos
Cuatro comandos que se ejecutan en orden, verificando sucesivamente el directorio, la Key, la conexión con Chrome y la capa de ejecución del navegador. Requisito previo: la terminal donde corre uv run jev sigue imprimiendo Jev Ultrafast: http://127.0.0.1:8766, y el navegador se abrió con 127.0.0.1:8766 (no localhost; el motivo está en la entrada de depuración Forbidden más abajo).
# 1. 当前目录对吗?——.env 从「当前目录」读取,必须在仓库根目录跑
pwd
# 应以 jev-ultrafast 结尾;不在就先 cd jev-ultrafast
# 2. 两个 Key 都配了吗?——应看到两行(值非空才算数)
grep -E "^(TYPESAFE_API_KEY|TEXT_MODEL_API_KEY)=." .env
# 顺手 echo $TYPESAFE_API_KEY 确认 shell 里没有旧值抢先——.env 不会覆盖已 export 的变量
# 3. Chrome 连得上吗?——官方诊断命令
uv run browser-harness --doctor
# 按提示在 Chrome 里允许远程调试
# 4. 浏览器执行层正常吗?——官方开发命令,不调用模型、不花 API 费
uv run python scripts/check_guards.py
# 在本地浏览器里跑执行守卫回归;脚本自己的说明:No model calls or external websitesDeberías ver: la 1 termina con jev-ultrafast; la 2 produce dos líneas; la 3 completa el diagnóstico de conexión; la 4 termina imprimiendo PASS: N browser guard checks; no model calls. Arregla por donde se rompa; si las cuatro pasan y sigue habiendo errores, el problema está casi seguro en la llamada al modelo o en la capa de decisión—sigue abajo para encontrar tu caso.
Resolución de problemas frecuentes
Arranque y conexión con Chrome (no conecta)
"Cannot reach local demo server"
Causa: la página del inspector no logra conectar con el servicio local—uv run jev no está corriendo, el puerto se cambió, o la página es una pestaña antigua. Esta frase aparece en la barra de estado (la rama de fetch fallido de app.js).
Solución:
- Reinicia en el directorio raíz del repositorio; la terminal debería imprimir:
uv run jev
# Jev Ultrafast: http://127.0.0.1:8766- Abre
http://127.0.0.1:8766en el navegador. Si cambiaste el puerto:TYPESAFE_DEMO_PORTdebe configurarse antes del arranque (demo.py lee el puerto fijo al importar el módulo); consulta las técnicas avanzadas de la lección de instalación y ejecución.
Al abrir la página solo se muestra "Forbidden"
Causa: se usó localhost:8766 en lugar de 127.0.0.1:8766. El servicio demo valida el encabezado Host y solo acepta 127.0.0.1:8766—este servicio escucha únicamente en la dirección de loopback local (demo.py se autodenomina Loopback-only inspector), y las peticiones POST reciben además {"error": "Local demo requests only"}.
Solución: cambia la barra de direcciones a http://127.0.0.1:8766 y actualiza.
Chrome no conecta, el panel no se mueve
Causa: Browser Harness necesita que Chrome permita la depuración remota; Chrome muestra el aviso en la primera conexión; si lo pierdes o lo rechazas, ya no conecta. Texto literal del README: Allow remote debugging in Chrome when prompted.
Solución:
- Ejecuta el comando oficial de diagnóstico, en el directorio raíz del repositorio:
uv run browser-harness --doctor- Cuando Chrome vuelva a mostrar el aviso de «permitir depuración remota», pulsa permitir.
- Si el diagnóstico pasa pero sigue sin moverse: ejecuta primero el
uv run python scripts/check_guards.pyde arriba—no llama al modelo y permite verificar la capa de ejecución del navegador por separado.
"A browser step is already running"
Causa: el paso anterior todavía se está ejecutando. El servicio demo usa un bloqueo global para garantizar que solo corra un paso de navegador a la vez; las peticiones que chocan con el bloqueo devuelven 409 y esta frase.
Solución: espera a que termine el paso actual; si quieres detener Run automatically mientras está en curso, pulsa Pause.
"Local demo failed; no automatic retry. Reset to recover."
Causa: el servicio demo envuelve cualquier excepción no capturada específicamente en este mensaje genérico 500 de respaldo. El desencadenante más común: TYPESAFE_API_KEY no está configurado en absoluto—model.py lee directamente os.environ["TYPESAFE_API_KEY"]; si falta, lanza KeyError, no se muestra el texto original y solo cae en este mensaje de respaldo.
Solución:
- Comprueba las dos Keys de
.env(el punto 2 de la verificación rápida de 60 segundos). - Haz Reset como indica el aviso: pulsa Start demo para reiniciar una vez.
- Quienes usan la biblioteca Agent verán directamente el traceback original (por ejemplo
KeyError: 'TYPESAFE_API_KEY'); corrige lo que falte según corresponda.
"Start a demo first"
Causa: en el inspector se pulsó Choose next / Execute choice / Run automatically sin haber hecho Start demo antes—el servicio demo rechaza estos comandos cuando todavía no se ha creado el agente.
Solución: primero escribe el objetivo, pulsa Start demo y luego ejecuta los botones de control.
"Enter 1–2,000 characters"
Causa: el objetivo está vacío o supera los 2000 caracteres (validación reset de demo.py).
Solución: escribe el objetivo en 1–2000 caracteres o menos. Pasar un objetivo vacío con la librería Agent da Supply a task (agent.py), con el mismo significado.
Key y llamadas al modelo (zona de errores frecuentes de TEXT_MODEL)
"TYPE_TEXT needs TEXT_MODEL_API_KEY; no text is hardcoded or guessed by the executor."
Causa: a .env le falta TEXT_MODEL_API_KEY. Esta comprobación solo se activa cuando la acción es TYPE_TEXT (field_text() de model.py), así que la demo puede arrancar y la página puede observarse, y solo se detiene al llegar a «escribir en un campo de texto» — la demo Flights necesita generar nombres de ciudades, no hay forma de evitarlo.
Solución:
- Añade en
.envla Key del modelo de texto (dónde conseguirla, ver la forma A/B/C del paso 3 de la lección de instalación y ejecución). - Ten en cuenta la regla de lectura:
.envse lee desde el directorio actual y no sobrescribe las variables homónimas ya exportadas en la shell — si ya lo rellenaste y sigue dando error, hazcd jev-ultrafasty vuelve a ejecutar, y compruebaecho $TEXT_MODEL_API_KEY.
"Model provider returned HTTP 401; no action executed."
Causa: el endpoint del modelo devolvió un código de estado de error, que se inserta en esta plantilla (el código fuente es f"Model provider returned HTTP {response.status_code}; no action executed."). 401 = Key no válida. Este mensaje TypeSafe se comparte con el modelo de texto, así que primero distingue de qué lado proviene:
| Cuándo se reporta | De qué lado es | Qué comprobar |
|---|---|---|
| Se reporta ya en la primera decisión | TypeSafe (la decisión se llama en cada ciclo) | TYPESAFE_API_KEY |
| Solo se reporta al llegar al paso de escribir texto | Modelo de texto (solo lo usa TYPE_TEXT) | Si TEXT_MODEL_API_KEY y TEXT_MODEL_BASE_URL coinciden |
Solución:
- Por el lado de TypeSafe: vuelve a la página Keys de la consola y copia de nuevo la Key; puedes verificarla con curl (resolución de problemas inicial tiene el comando completo).
- Por el lado del modelo de texto: confirma que la Key sea del endpoint que configuraste (una Key de OpenRouter configurada con el endpoint de DeepSeek es 401).
- El significado de otros códigos de estado (400/413/415/422, etc.) está en la tabla de códigos de estado de API de consulta rápida — 429/529/503 no se reportan de inmediato, ver más abajo "Model provider returned HTTP 429/529/503".
"Model connection failed; no action executed."
Causa: el cliente HTTP lanzó una excepción a nivel de red — no se puede conectar al endpoint, fallo de resolución DNS y similares; la solicitud ni siquiera llegó a enviarse (model.py captura httpx.HTTPError y luego lanza este mensaje).
Solución:
- Comprueba si la red puede acceder a
api.typesafe.aiy a tuTEXT_MODEL_BASE_URL. - Comprueba la ortografía del endpoint: en
TEXT_MODEL_BASE_URLel error habitual es que falte o sobre un/v1(valor de ejemplohttps://openrouter.ai/api/v1, DeepSeek usa por defectohttps://api.deepseek.com/v1).
"Model provider returned HTTP 429/529/503; no action executed." (limitación de tasa y sobrecarga)
Causa: el endpoint del modelo devolvió 429 (limitación de tasa) / 529 (sobrecarga) / 503. Estos códigos de estado no se reportan de inmediato: el código intenta en total 3 veces (reintenta 2 veces, con intervalos de 0.5s y 1s); solo si el intento 3 sigue fallando se inserta en la plantilla de códigos de estado anterior y se reporta Model provider returned HTTP 429; no action executed. (529 y 503 con la misma estructura).
En el código fuente hay además un mensaje de respaldo "Model unavailable" (model.py L27), pero según el flujo de control actual es inalcanzable — agotados los reintentos de 429/529/503 se usa la plantilla de códigos de estado, y este mensaje no aparece en la interfaz; si lo encuentras buscando en el código fuente, asígnalo a esta entrada.
Solución: espera un momento y vuelve a ejecutar; si aparece con frecuencia, revisa la cuota — por el lado de TypeSafe en la página rate-limits de la consola, y por el lado del modelo de texto en la página de facturación de tu proveedor.
"Invalid TypeSafe response; no action executed."
Causa: la respuesta de decisión no pasó la validación local (model.py de validate_choice(): la opción elegida debe estar entre las candidatas, cada opción debe tener probabilidad, los valores deben estar en 0–1 y la suma de probabilidades debe ser aproximadamente 1). Es un guardián de «la respuesta no cumple el contrato», no un problema de tu configuración.
Solución: primero vuelve a ejecutar tal cual (es algo ocasional); si persiste, exporta el trace (ver «¿Sigue sin funcionar?») y llévalo como retroalimentación.
"Text helper returned no valid field value; nothing typed."
Causa: la salida del modelo de texto no cumple el contrato — debe ser un JSON con solo la clave text, cuyo valor es una cadena no vacía de no más de 2000 caracteres (reglas de análisis de model.py). Dos disparadores habituales:
| Disparador | Mecanismo |
|---|---|
| Falta un valor obligatorio en el objetivo | Las instrucciones del modelo establecen explícitamente: si falta un valor, devolver {"text": null} y nunca inventar datos personales (el TEXT_VALUE de questions.py) — el null falla al analizarse y no se escribe nada |
| El modelo no sigue las reglas | Devolvió un párrafo de texto explicativo en lugar de JSON — el informe de rendimiento oficial menciona justamente que durante el sondeo se rechazó a un modelo de este tipo |
Solución:
- Escribe en el objetivo los valores que la tarea necesita (fechas, nombres de ciudades y similares, no dejes que el modelo los adivine).
- Si aún no funciona, cambia de modelo de texto y mantén
TEXT_MODEL_REASONING=none(los modelos sin razonamiento improvisan menos). - Un valor escrito con errores (no el hecho de no escribir) se maneja igual: la prueba oficial incluso rechazó a un modelo que intercambió el origen y el destino; antes de cambiar de modelo, pruébalo con tareas pequeñas.
Interrupciones de ejecución y presupuesto (no avanza)
"Target changed or is covered. Observe again."
Causa: la revisión de seguridad previa a la ejecución detectó que el objetivo cambió: quedó cubierto, oculto, deshabilitado, fuera del viewport, o ya no es el nodo que era al observar. Es el guardián haciendo su trabajo, no un bug: la salida del modelo siempre referencia solo elementos reales observados, y antes de ejecutar se vuelve a verificar su posición geométrica.
Solución: volver a observar y decidir de nuevo. En ejecución automática (sin Slow motion) cada paso avanza por tick, y estos errores de stale se descartan automáticamente con una nueva observación, así que ni los ves; en modo manual paso a paso o con cámara lenta se pausa mostrando el texto original, y basta con pulsar una vez Choose next para decidir de nuevo.
"Page changed since the decision. Choose again."
Causa: la familia stale: la página cambió después de tomarse la decisión, y la decisión anterior queda anulada. Variantes de la misma familia: Page changed before text generation. Choose again. (la página cambió antes de escribir), Page changed since this decision. Observe again. (revisión previa a la ejecución), Document changed during evaluation / Document is navigating (la página estaba cambiando durante la observación).
Solución: igual que antes, volver a observar. Dos detalles:
- El valor escrito no se genera en vano: solo cuando la entrada del helper de texto permanece exactamente igual, el reintento reutiliza el último valor generado (Reuse an interrupted text request en el README).
- Si aparece con frecuencia, significa que la página tiene muchas animaciones o cargas; espera un momento antes de ejecutar o cambia a una página más estable.
"Page did not settle"
Causa: en 10 observaciones consecutivas (con intervalos de 20 ms) la página no se estabilizó: las animaciones no paran o sigue cargando.
Solución: espera a que la página se calme antes de ejecutar; algunas páginas pesadas (animaciones al hacer scroll, skeleton screens permanentes) pueden simplemente no ser adecuadas.
"Dropdown execution was not confirmed; inspect before retrying."
Causa: el resultado de ejecutar un <select> nativo no fue confirmado, o la ejecución fue interrumpida (variante del texto original: Dropdown execution was interrupted; inspect before retrying.). El código opta aquí por detenerse de forma conservadora en lugar de reintentar a ciegas: reintentar podría causar una selección duplicada.
Solución: volver a observar (Choose next / reejecutar), para que el agente decida de nuevo basándose en la página nueva.
"Observe and choose before acting"
Causa: en modo manual se pulsó Execute choice sin una decisión, o tras obtener la decisión cambió la huella de la página y la decisión ya fue consumida.
Solución: pulsa una vez Choose next para obtener una decisión nueva, y luego Execute choice.
"Stopped at the 60-action demo budget"
Causa: se agotó el presupuesto estricto de una sola ejecución: como máximo 60 acciones ejecutadas (MAX_STEPS = 60). Las llamadas de decisión tienen otro límite, 120 (MAX_STEPS × 2); al alcanzarlo se reporta Reached the demo's model-call budget.
Solución: si la tarea es demasiado grande, divídela en partes más pequeñas: el parámetro del ejemplo oficial de examples/run.py se llama precisamente 'A narrow goal', y escribir un objetivo acotado es la recomendación oficial. Si no terminó dentro del presupuesto, normalmente indica que el objetivo era demasiado amplio o que la página no es adecuada (ver el grupo siguiente).
"This run has stopped. Start a fresh demo."
Causa: el estado ya es done o blocked y se sigue pidiendo una decisión nueva: esa ejecución ya terminó.
Solución: pulsa Start demo para iniciar una ejecución nueva.
La barra de estado muestra "Stopped · no supported next action" (blocked)
Causa: dos orígenes posibles: el modelo eligió activamente BLOCKED (definición de las instrucciones: no hay operaciones compatibles que hagan avanzar la tarea), o durante 3 acciones ejecutadas consecutivas (ninguna de ellas WAIT) la página no cambió en absoluto: el código determina que está atascado y pasa automáticamente a blocked.
Solución:
- Mira los últimos 3 pasos del Decision trail: qué se pulsó y por qué la página no cambió.
- Contrasta con el grupo siguiente, la «lista de no soportados»: la causa raíz más común de blocked es que la página contiene controles que no se pueden ejecutar.
- Acota y concretiza el objetivo, y reinicia el demo.
Resultados incorrectos y límites de página (se desvió)
La barra de estado muestra "Jev reports complete · inspect the page", pero la página no es la deseada
Causa: el modelo eligió DONE, pero DONE nunca es prueba de éxito: en Evidence and limits lo oficial lo dice sin rodeos: aunque se elija DONE, hay que verificar el resultado de forma independiente. La segunda parte de la barra de estado (inspect the page) es justamente el recordatorio de que lo compruebes personalmente.
Solución:
- Para tareas importantes, añade verificación independiente. El ejemplo oficial es
examples/flights.pydeverify(): verifica en la página de resultados, punto por punto, el trayecto de ida, el origen, el destino, la fecha y la visibilidad de los resultados: no confía en el DONE del modelo; si la verificación falla, sale y reportaFinal page did not satisfy the route/date checks. - Escribe con claridad la condición de parada en el objetivo. El objetivo del ejemplo oficial de Flights termina con
Stop when …; escribe siguiendo esa fórmula. - Los objetivos del tipo «abrir cierto resultado» requieren especial atención: las instrucciones del modelo establecen explícitamente que «solo encontrar el enlace coincidente no cuenta como completado».
El control no responde al pulsarlo / no aparece en la tabla de elementos (shadow DOM, canvas, subida de archivos…)
Causa: te topaste con los límites del MVP. El DOM reader solo reconoce controles HTML y ARIA comunes y no implementa el algoritmo completo de accessible-name. Según la lista oficial de Limits, lo siguiente no está soportado en ningún caso:
| No soportado | Ejemplos |
|---|---|
| shadow roots / frames | controles internos renderizados por frameworks de componentes |
| canvas | interacciones de mapas y lienzos |
| subida de archivos | <input type="file"> |
| apertura de nuevas pestañas | enlaces que abren un tab nuevo al pulsarlos |
| scroll anidado | contenedores con scroll interno |
| componentes de teclado arbitrarios | atajos de teclado, editores de texto enriquecido |
Solución: antes de empezar la tarea, coteja la lista y filtra; por ahora no intentes forzar páginas que involucren estos controles (el paso 4 de la lección de principios incluye la misma lista de límites); cambia a una página o tarea que solo contenga controles convencionales. Ten en cuenta además: la pestaña del agente comparte tu perfil de Chrome existente: el estado de sesión afecta al contenido de la página, así que piensa en esto al diagnosticar un «la página no es lo que esperaba».
El texto escrito es incorrecto, o no se escribió el texto que debía
Causa: la cadena la infiere el helper de texto a partir del objetivo, no la escribe Jev. Texto incorrecto = el modelo del helper entendió mal el objetivo; si no escribe nada = devolvió {"text": null} según las reglas (cuando el objetivo carece de un valor obligatorio, se niega a inventarlo; véase arriba la entrada nothing typed).
Solución: escribe el valor obligatorio tal cual en el objetivo («September 20, 2026» en lugar de «el mes que viene»); si aún falla, cambia el modelo de texto, sondeando primero con una tarea pequeña — oficialmente fue precisamente con seis llamadas de sondeo como se descartaron los modelos que invertían ciudades y que emitían comentarios (véase interpretación de rendimiento).
Rellena todo pero no envía, escribe texto pero no elige la sugerencia
Causa: en las instrucciones del modelo estas reglas están literalmente fijadas: tras rellenar los campos obligatorios hay que enviar («los campos rellenados no equivalen a una búsqueda ya aplicada»), y tras escribir la consulta hay que elegir la sugerencia de autocompletado que coincida. Si no lo hace, casi siempre es un problema de sincronización — tras escribir, el código espera como máximo 200 ms a que aparezca la sugerencia, y en sitios donde las sugerencias cargan lento puede que no llegue a la siguiente observación.
Solución: volver a ejecutar tal cual suele bastar; si sigue atascado en el mismo punto, escribe el objetivo con más precisión (qué enviar, dónde detenerse) o cambia a una página cuyas sugerencias carguen rápido.
¿Sigue sin funcionar?
Primero aísla, luego recopila evidencia y, por último, pregunta llevando la evidencia.
La herramienta de aislamiento son los dos scripts incluidos en el repositorio (ambos en scripts/, de la sección Development del README):
# 只测浏览器执行层:本地页面、不调用模型、不花钱
uv run python scripts/check_guards.py
# 测完整链路:浏览器只开本地 fixture 页面,但会发起真实模型调用(产生付费 API 费用)
uv run python scripts/smoke.pycheck_guards.py pasa, smoke.py también pasa, pero el sitio web real falla — el problema probablemente esté en ese sitio en sí (límites de controles, tiempos de carga); consulta la lista de no soportados.
Recopila evidencia, con tres cosas basta:
| Evidencia | Cómo obtenerla | Qué contiene |
|---|---|---|
| Trace de decisiones | En la parte inferior del inspector, el botón Export trace ↓ | Descarga typesafe-browser-trace.json: historial completo de decisiones, probabilidades, objetivo, URL de la página y texto visible (sin capturas) |
| Qué vio el modelo | Sección plegable de la página What the model sees | El cuerpo completo de la petición enviada al modelo, consultable campo por campo |
| Texto original del error | La frase del recuadro rojo | Todos los H4 de esta página coinciden |
⚠️ Revísalo antes de enviar
El trace contiene la URL de la página y el texto visible, que puede incluir información de tu cuenta; ten en cuenta además: el ejemplo live y los scripts de grabación generan llamadas de API de pago (palabras textuales del README), así que sé consciente de ello antes de reproducirlo repetidamente.
Dónde preguntar:
| Canal | Cuándo acudir |
|---|---|
| Esta lección + instalación y ejecución | Autocompruébalo dos veces primero; la mayoría de los problemas no llegan a este punto |
| resolución de problemas iniciales / referencia rápida de API | problemas de códigos de estado del lado de la API de TypeSafe |
| GitHub Issues | Defectos de Ultrafast en sí: incluye trace + texto del error + objetivo y URL |
| TypeSafe Discord | Problemas del lado de la API de decisiones (Jev); los oficiales dicen que si está roto, repórtalo directamente |
| Browser Use Cloud | Problemas al usar la versión alojada de BU Ultrafast (model: "bu-ultrafast") |
Punto de control ✅
- 60 segundos: he ejecutado los cuatro comandos de verificación rápida y sé en qué capa se atasca
- Distingo tres tipos de errores: los stale se autocuran, 429/529/503 se reintentan automáticamente, y configuración/presupuesto/límites requieren intervención manual
- Con estado done no doy por terminado sin más — a las tareas importantes les añado una verificación independiente (el verify() de flights.py es el modelo a seguir)
- He repasado la lista de no soportados: shadow DOM, frames, canvas, subidas, pestañas nuevas, scroll anidado, componentes de teclado
- Al preguntar incluyo typesafe-browser-trace.json, el texto del error, el objetivo y la URL
Resumen de la lección
✅ Para depurar, primero determina la capa: servicio local → conexión de Chrome → llamada al modelo → ejecución de decisiones; los errores de cada capa tienen aspecto distinto.
✅ Todos los textos de error de jev-ultrafast provienen del código fuente del repositorio y se pueden buscar palabra por palabra; los títulos H4 son el texto literal del error: cópialos para buscar o preguntar.
✅ Tres tratamientos: los de tipo stale se dejan a la reobservación automática, 429/529/503 se dejan al reintento del código, y solo los de configuración/presupuesto/límites requieren que actúes.
✅ DONE no es prueba de éxito, con blocked consulta primero la lista de no soportados, y las 60 acciones son un presupuesto estricto — con estas tres reglas en mente, la mitad de los «descarrilamientos» se pueden evitar por adelantado.
Referencia rápida de señales clave:
| Señal | En qué capa | Primer paso |
|---|---|---|
| Cannot reach local demo server / Forbidden | Servicio local | Vuelve a ejecutar uv run jev; abre 127.0.0.1:8766 |
| El panel no se mueve | Conexión de Chrome | uv run browser-harness --doctor, permite la depuración remota |
| TYPE_TEXT needs TEXT_MODEL_API_KEY | Llamada al modelo (lado de texto) | Completa la Key en .env; atención a cwd y setdefault |
| Model provider returned HTTP 401 | Llamada al modelo (Key no válida) | Primero distingue si es TypeSafe o el modelo de texto, y luego vuelve a copiar la Key |
| Model provider returned HTTP 429/529/503 | Llamada al modelo (limitación/sobrecarga) | Espera un poco y vuelve a ejecutar; comprueba la cuota |
| Target changed or is covered | Ejecución de decisiones (stale) | Reobserva; en modo automático se autocura |
| Stopped at the 60-action demo budget | Ejecución de decisiones (presupuesto) | Escribe objetivos más acotados y divide las tareas en partes pequeñas |
| Estado done pero el resultado es incorrecto | Verificación del resultado | Comprobar personalmente; añadir una verificación independiente al estilo de flights.py |
| Estado blocked | Límites de la página | Consultar la lista de no soportados, cambiar de página o modificar el objetivo |
Vista previa de la próxima lección
Con esto termina la parte sobre navegadores. La próxima lección Jev 1.13 Manual de trampas: 9 modos de fallo y enfoques alternativos vuelve al modelo Jev en sí; fuera de Ultrafast, es aplicable a todas las aplicaciones Jev. Aprenderás:
- Los 9 modos de fallo de la documentación oficial de jaggedness: interpretación literal, conteo aritmético, comparación de fechas, referencia indirecta…
- El enfoque alternativo para cada modo de fallo: la aritmética al código, extraer componentes de las fechas, filtrar primero los state grandes
- Cómo estos hábitos de formular preguntas retroalimentan tus objetivos al escribir en Ultrafast y otras aplicaciones Jev
Tutoriales relacionados
- Instalación y ejecución de Ultrafast: uv sync más dos API Key
- Ejecutar Google Flights: una búsqueda real completada en 7 segundos
- Qué hacer si no se instala o no se ejecuta: resolución de problemas iniciales
Apéndice: referencia del código fuente
Haz clic para expandir y ver las ubicaciones del código fuente
Última actualización: 2026-11-04 (repositorio github.com/browser-use/jev-ultrafast, fuente de información local sources/jev/repo-ultrafast/)
| Función | Ruta del archivo | Ubicaciones clave |
|---|---|---|
| Texto original del error: conexión/HTTP/reintentos | jev_ultrafast/model.py | L15–27 post_json (L20 fallo de conexión, L21–23 reintento automático ante 429/529/503, en total 3 intentos, L25 plantilla de código de estado HTTP, L27 texto de respaldo «Model unavailable», inalcanzable con el flujo de control actual); L12 timeout=25 del cliente |
| Texto original del error: validación de la respuesta de decisión | jev_ultrafast/model.py | L30–45 validate_choice (L44 Invalid TypeSafe response) |
| Texto original del error: helper de texto | jev_ultrafast/model.py | L160–198 field_text (L163 texto original de Key faltante, L187–193 validación del contrato JSON, L193 nothing typed) |
| Solicitud TypeSafe y lectura de Key | jev_ultrafast/model.py | L119 (api.typesafe.ai/v1/systemone + os.environ["TYPESAFE_API_KEY"], lanza KeyError si falta) |
| Texto original del error: presupuesto y máquina de estados | jev_ultrafast/agent.py | L74 detenido, L75–76 presupuesto de llamadas al modelo (MAX_STEPS×2=120), L88–89 observar antes de ejecutar, L96/L107–108 texto original de stale, L102–104 presupuesto de acciones 60, L153–158 3 veces consecutivas sin cambios→blocked |
| Texto original del error: stale y guardas de ejecución | jev_ultrafast/browser.py | L86 Page did not settle, L102 la página cambió antes de la ejecución, L130–131/L162–163 desplegable sin confirmar o interrumpido, L164 objetivo sobrescrito; L16 StalePage(ValueError) |
| Texto original del error: servicio demo | jev_ultrafast/demo.py | L16 puerto (configurar TYPESAFE_DEMO_PORT antes de iniciar), L23–29 lectura de .env (cwd + setdefault), L48–52 escenarios y caracteres 1–2000, L64–65 Start a demo first, L111–112 bloqueo de paso único 409, L122–123 respaldo 500 |
| Barra de estado del inspector y visualización de errores | jev_ultrafast/static/app.js | L63 Paused · needs attention, L82–88 cinco textos de estado, L173–183 bucle automático (auto-sanación por tick vs pasos lentos), L217–235 exportación de trace (sin capturas), L243 Cannot reach local demo server |
| Botones de la interfaz y secciones plegables | jev_ultrafast/static/index.html | L56–59 Choose next / Execute choice / Run automatically / Pause, L126 Export trace ↓, L133 What the model sees |
| Instrucciones del modelo (DONE/BLOCKED/envío/reglas de sugerencias) | jev_ultrafast/questions.py | L3–14 NEXT_ACTION, L21–24 TEXT_VALUE (devuelve null si falta un valor, no inventa datos personales), L26 MAX_STEPS = 60 |
| Instalación, --doctor, depuración remota, lista de limitaciones | README.md | L53–68 Try it (incluye uv run browser-harness --doctor), L118–126 Evidence and limits (DONE requiere verificación independiente; shadow roots/frames/canvas/subida de archivos/nueva pestaña/scroll anidado/componentes de teclado no compatibles; la pestaña usa el perfil de Chrome existente), L128–138 Development (check_guards, aviso de pago) |
| Lista de limitaciones (texto original de Limits) | docs/performance.md | L53–55; L49 detectar modelos rechazados (escribir ciudades al revés / generar comentarios de salida) |
| Ejemplo de verificación independiente | examples/flights.py | L18–38 verify() verificación punto por punto, L63–64 Final page did not satisfy the route/date checks |
| Script local de regresión de guardas | scripts/check_guards.py | L1 docstring (No model calls or external websites), L133 impresión al final PASS: N browser guard checks; no model calls |
| Script local de prueba de humo con fixtures | scripts/smoke.py | L1 docstring (API de pago), L19 --max-actions (por defecto 15), L25 imprime el directorio de trace |