Docs

Solución de problemas

Qué revisar cuando no llega nada, cuando un bloqueador de anuncios, CORS o una política de seguridad de contenido bloquean las peticiones, cuando los source maps no aplican y cuando las sesiones parecen duplicadas.

Aplica a MotorNube Al lanzar

Ver como Markdown
En esta página
  1. Empieza aquí: la lista de chequeo
  2. Enciende debug
  3. Mira la petición
  4. Lee la respuesta, no solo el estado
  5. Mira en el lugar correcto
  6. Alojamiento propio: pregúntale al motor
  7. No llega nada
  8. Desde un servidor Node
  9. Orígenes y CORS
  10. Bloqueadores de anuncios
  11. Política de seguridad de contenido
  12. Los source maps no aplican
  13. Sesiones duplicadas o partidas
  14. Una traza no se une
  15. Falta una grabación
  16. Si sigues atascado

Esta página es para cuando el SDK está instalado y falta algo. Cubre los tres SDK, para el motor de código abierto y para Sypnia Cloud; los pasos que aplican solo a uno están marcados.

Empieza aquí: la lista de chequeo

Hazlos en orden. La mayoría de los casos termina en uno de los cuatro primeros.

  1. Enciende debug

    Pon debug: true en init (en withSypnia para Next.js) y recarga.

    Deberías ver
    En la consola del navegador, una línea [sypnia] started con el prefijo de la llave del proyecto, el endpoint, el entorno y la versión, y luego una línea por cada evento. Si ves [sypnia] off:, lo sigue el motivo.
  2. Mira la petición

    En las herramientas de desarrollo, pestaña Network, filtra por ingest y haz clic en algo de tu app. Espera 10 segundos.

    Deberías ver
    Un POST a …/v1/ingest/events con estado 200 y un cuerpo como {"accepted": 3, "dropped": 0}.
  3. Lee la respuesta, no solo el estado

    Un 200 puede decir igual que se descartaron eventos: {"accepted": 0, "dropped": 3, "dropped_reasons": {…}}. Los motivos están más abajo.

  4. Mira en el lugar correcto

    En Sypnia, elige el entorno que envía tu app. Una app que corre en localhost con el fragmento del inicio rápido envía development, y las listas muestran production por defecto. Las sesiones y los números están completos en menos de 10 minutos; un problema nuevo aparece en menos de 2 minutos.

  5. Alojamiento propio: pregúntale al motor

    Motor En la máquina que corre el motor:

    Terminal
    sypnia doctor
    Deberías ver
    Una línea por cada pieza de la que depende el motor (ajustes, base de datos, almacenamiento, dirección pública, proveedor de IA, webhook, reloj), cada una ok, y all checks passed. Una línea que dice FAIL nombra el ajuste que hay que cambiar.

    sypnia doctor revisa el motor, no tu app. Si pasa y los eventos siguen sin verse, la causa está en esta página.

No llega nada

Qué vesCausaQué hacer
Ninguna petición, y [sypnia] off: no projectproject está vacío. Suele ser una variable de entorno que no existe en el paquete del navegador.Imprime el valor que pasas. En Vite la variable debe empezar por VITE_; en Next.js usa withSypnia.
Ninguna petición, y [sypnia] off: opted outlocalStorage tiene sypnia:off. Alguien llamó a optOut(), o lo dejó una configuración de pruebas.Llama a optIn(), o borra la clave.
Ninguna petición, y [sypnia] off: disabledenabled: false.Revisa la condición que pasas.
Ninguna petición solo en algunas páginasLa ruta está en ignoreRoutes.Quítala de la lista.
Ninguna línea en la consolainit nunca corrió: el archivo no se importa, o la etiqueta script no tiene data-project y nada llama a init.Importa el archivo primero en tu punto de entrada.
La petición sale en rojo: net::ERR_BLOCKED_BY_CLIENTUn bloqueador de anuncios o una extensión de privacidad.Mira la sección Bloqueadores de anuncios.
La petición sale en rojo: bloqueada por Content-Security-PolicyLa política de tu sitio no permite la dirección.Mira la sección Política de seguridad de contenido.
401 unauthorizedLa llave no existe o está revocada, o es de otro motor.Copia la llave otra vez. Una llave de Sypnia Cloud no sirve en un motor con alojamiento propio, ni al revés.
403 wrong_credentialSe usó un token de API (sps_…) o el token raíz como project.Usa la llave de ingesta (spk_…). Revoca el token: quedó expuesto.
403 origin_not_allowedEl proyecto lista orígenes permitidos y el de esta página no está.Mira la sección Orígenes y CORS.
413 payload_too_largeNo viene del SDK: mantiene los lotes muy por debajo del límite. Un proxy intermedio está reescribiendo el cuerpo.Revisa el proxy.
429 rate_limitedUna dirección envía demasiado rápido con esta llave.El SDK espera y reintenta solo. Si sigue, busca un bucle que lanza errores o llama a track.
200 con dropped_reasons: { limit_reached: … }El proyecto llegó a un límite.Mira Muestreo y cuotas.
200 con dropped_reasons: { invalid: … }A un evento le falta un campo obligatorio. Desde un SDK oficial es un error nuestro; desde tu propio cliente, compáralo con el esquema de eventos.Repórtalo con el evento que imprime debug.
200, nada descartado, nada en SypniaEntorno equivocado, proyecto equivocado, o hace menos de 10 minutos.El paso 4 de arriba.
Alojamiento propio: la petición falla con un error de conexión o de certificadoendpoint no es la URL base pública del motor, o el motor no es alcanzable desde internet por HTTPS.Abre <endpoint>/healthz en un navegador. Corre sypnia doctor --only address.

Desde un servidor Node

Qué vesCausaQué hacer
No se imprime ningún server_request con debug: trueinit corrió después de crear el servidor, o en otro proceso.Importa ./instrument en la primera línea del archivo de entrada.
Se imprimen eventos, y luego send failedEl servidor no alcanza el endpoint: un firewall, un proxy, el DNS.curl -i <endpoint>/healthz desde la misma máquina.
Nada desde una función serverlessLa función se congeló antes del envío.Usa wrapFetchHandler, o await flush() antes de devolver.
Solo algunas rutasLos archivos estáticos, OPTIONS e ignoreRoutes no se trazan.Es lo esperado.

Orígenes y CORS

A tres cosas distintas se les llama problemas de CORS.

1. La ingesta rechaza el origen de tu página. La ingesta responde CORS para cualquier origen por su cuenta; no configuras nada en ella. La excepción es un proyecto que lista orígenes permitidos (settings.allowed_origins): entonces los demás orígenes reciben 403 origin_not_allowed. Agrega el origen, con su esquema y su puerto, o vacía la lista:

Terminal
curl -X PATCH "https://api.sypnia.com/v1/projects/shop" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"allowed_origins": ["https://shop.example", "http://localhost:5173"]}}'

Las direcciones de vista previa de los constructores de apps y de los proveedores cambian con cada despliegue. O dejas la lista vacía, o no esperes que las vistas previas reporten.

2. Tu propia API rechaza los encabezados de traza. Si tu API está en otro origen y figura en traceTargets, el navegador le pregunta primero si traceparent y x-sypnia-session están permitidos. Si tu API dice que no, tus propias llamadas fallan. Permite ambos encabezados en la respuesta CORS de la API, o quita la API de traceTargets (usa recordTargets para seguir registrando sus llamadas sin encabezados).

HTTP
Access-Control-Allow-Headers: content-type, authorization, traceparent, x-sypnia-session

3. Un motor con alojamiento propio detrás de tu propio proxy. Deja que el motor responda OPTIONS él mismo. Si el proxy agrega sus encabezados CORS encima de los del motor, los navegadores rechazan la respuesta porque el encabezado aparece dos veces.

Bloqueadores de anuncios

Algunos bloqueadores de anuncios y extensiones de privacidad bloquean por nombre de host las peticiones a servicios de monitoreo. La app sigue funcionando: el SDK falla en silencio. Pierdes las sesiones de esos visitantes.

La solución es enviar por tu propio dominio. Agrega a tu sitio una ruta que reenvíe a la ingesta, y pon endpoint con esa ruta. Una ruta del mismo origen de la página es un endpoint válido.

Next.js

next.config.ts
const nextConfig: NextConfig = {
  async rewrites() {
    return [{ source: '/_sy/:path*', destination: 'https://ingest.sypnia.com/:path*' }];
  },
};
instrumentation-client.ts
init({ endpoint: '/_sy' });

Conserva X-Forwarded-For: los límites de frecuencia son por dirección, y sin él todos tus visitantes comparten la de tu proxy. Con la etiqueta script, sirve sdk.js por la misma ruta: src="/_sy/v1/sdk.js" y data-endpoint="/_sy". En un motor con alojamiento propio, reenvía a la URL base de tu motor.

Un bloqueador que bloquea por la forma de la petición y no por el host no se puede esquivar, y no se debe: ese visitante pidió que no lo midan.

Política de seguridad de contenido

Si tu sitio envía una Content-Security-Policy, permite a Sypnia en ella. Reemplaza el host por el de tu motor si tienes alojamiento propio, o por 'self' si envías por tu propio dominio.

DirectivaAgregaHace falta para
connect-srchttps://ingest.sypnia.comEnviar eventos y grabaciones.
script-srchttps://ingest.sypnia.comSolo la etiqueta script. No hace falta con el paquete de npm.

El SDK no usa scripts en línea, ni eval, ni workers.

Los source maps no aplican

Una pila sigue mostrando checkout-3f9c.js:1:48211 en vez de src/checkout/checkout.tsx:142.

RevisaCómoArreglo
La versión del evento es la versión para la que subiste.Abre una ocurrencia del problema y lee su versión. Compárala con --release en tu compilación. Un hash de commit completo y sus primeros 7 caracteres son versiones distintas.Usa una sola expresión para ambos. En Next.js, withSypnia lo hace.
El evento tiene versión.debug: true imprime release al arrancar.Pasa release a init.
Los source maps llegaron.curl "https://api.sypnia.com/v1/releases/4f2a91c/sourcemaps" -H "Authorization: Bearer $SYPNIA_API_TOKEN": cada archivo debe decir "uploaded": true.Corre la subida otra vez; se salta lo que ya está.
Las rutas coinciden.En esa lista, url_path debe ser la ruta desde la que el navegador carga el archivo: /assets/checkout-3f9c.js.Pon --url-prefix en sypnia sourcemaps upload.
Los source maps se generaron.Tu empaquetador debe escribir archivos .map: build.sourcemap: 'hidden' en Vite, devtool: 'hidden-source-map' en webpack.Enciéndelos, y bórralos después de la subida.
La subida corrió antes de que el despliegue quitara los archivos.Lee el registro de la compilación: la subida imprime cuántos source maps encontró.Sube justo después de empaquetar.
El fallo es anterior a la subida.Los source maps aplican desde la siguiente ocurrencia del problema.Espera la siguiente, y pide un análisis nuevo.
Un source map pesa más de 64 MB.La subida lo lista como omitido.Divide el paquete.
La pila es del servidor de una app Next.js.—Los source maps del servidor están Planeado.

La agrupación nunca depende de los source maps: el problema es el mismo problema antes y después.

Sesiones duplicadas o partidas

Una visita aparece como varias sesiones.

CausaCómo saberloQué hacer
El navegador bloquea el almacenamiento (modo privado en algunos navegadores, ajustes estrictos, una vista web incrustada sin almacenamiento).debug: true imprime storage unavailable, session kept in memory. Cada carga completa de página es entonces una sesión nueva.Nada en el SDK puede arreglarlo. Una app de una sola página no se ve afectada, porque no recarga.
Dos orígenes. shop.example y app.shop.example, o http y https, tienen almacenamiento separado.Las sesiones vienen en pares con hosts distintos.Sirve la app desde un solo origen. Las sesiones no se pueden compartir entre orígenes al lanzar.
La página está incrustada en un marco de otro sitio.Sesiones desde el sitio que la incrusta.Es lo esperado: un marco tiene su propio almacenamiento.
30 minutos sin actividad.El hueco entre las dos sesiones es de más de 30 minutos.Es lo esperado.
Se identificó a otra persona, o se llamó a identify(null).Las sesiones tienen personas distintas.Es lo esperado. No llames a identify(null) en cada carga de página antes de saber quién tiene sesión iniciada.
El SDK se carga dos veces desde dos compilaciones distintas.Dos líneas [sypnia] started.La segunda no hace nada, por diseño: una sola sesión. Si ves eventos dobles, repórtalo.
Pruebas o bots.Muchas sesiones de una sola página desde la misma clase de dispositivo.Corre las pruebas con enabled: false, o con localStorage.setItem('sypnia:off', '1').

Una traza no se une

La llamada del navegador y la petición del servidor aparecen como dos trazas.

  • La API está en otro origen y no figura en traceTargets: el encabezado no se envía. Agrégala.
  • El CORS de la API no permite traceparent: mira arriba.
  • Un proxy o una pasarela intermedia quita o reemplaza traceparent. Déjalo pasar.
  • El navegador y el servidor envían a proyectos distintos o con valores distintos de environment. Una traza une un proyecto y un entorno.
  • El SDK del servidor arrancó después que el servidor. Importa ./instrument primero.

Falta una grabación

  • La sesión no estaba en la parte muestreada y nada salió mal en ella. Es lo normal: mira Muestreo y cuotas.
  • La sesión sigue activa. Una grabación se puede ver cuando la sesión lleva 2 minutos inactiva, o terminó.
  • La ruta está en replay.blocked_routes del proyecto o en replay.blockedRoutes.
  • El proyecto llegó a su límite de grabaciones. La línea de tiempo de la sesión lo dice.
  • replay: false en init.
  • A tu token le falta el permiso replay: ves que existe una grabación y no puedes abrirla.

Si sigues atascado

Reúne esto antes de preguntar: el nombre y la versión del SDK, la salida de la consola con debug: true desde el arranque hasta el primer envío, el estado y el cuerpo de la petición a la ingesta y, con alojamiento propio, la salida de sypnia doctor. Quita el token de API si aparece alguno; la llave de ingesta es pública. Dónde preguntar está en Soporte para Sypnia Cloud y en Contribuir para el motor de código abierto.

Secciones

Empieza aquíQué es Sypnia, cómo funciona, qué es código abierto y qué es la nube de pago, y las dos maneras de recibir tu primer problema en palabras claras.ConceptosLas diez ideas de las que está hecho Sypnia, cada una definida con precisión, desde un proyecto y sus llaves hasta los problemas, las trazas y las alertas.SDKCómo envía tu app los datos a Sypnia. Un SDK para el navegador, uno para Node, uno para Next.js, y la entrada de OpenTelemetry para cualquier otro backend.El agenteCómo analiza Sypnia un problema, qué escribe, qué le envía a un modelo y qué nunca hace.MCP y skillsConecta tu agente de código a Sypnia para que pregunte qué está fallando en producción, lea lo que necesita para arreglarlo y configure Sypnia por ti.Referencia de la APILa API HTTP de Sypnia: una sola API para el motor de código abierto y para Sypnia Cloud, con cada endpoint, parámetro, respuesta y error.Referencia de la CLIEl comando sypnia: cómo instalarlo, qué variables lee, qué significan sus códigos de salida y dónde está documentado cada comando.Alojamiento propioQué corres cuando alojas tú mismo el motor de Sypnia, qué necesitas, cuánto cuesta y qué no tienes frente a Sypnia Cloud.Cómo está construido el motorTodo el motor de Sypnia en una página, desde un clic en tu app hasta la frase que lee tu agente de código, con las reglas de diseño y el código que las sostiene.Sypnia CloudCómo funciona el servicio pago, desde las organizaciones y los roles hasta los planes, los límites, la facturación, dónde viven tus datos, la GitHub App y el soporte.Privacidad y seguridadQué recoge Sypnia de tu app y de sus usuarios, qué no recoge nunca, cómo funciona el enmascarado, cómo eliminar datos y cómo se protege el servicio.LicenciasQué licencia cubre cada parte de Sypnia, qué puedes hacer con ella, cómo se puede usar el nombre, y los términos de una contribución.GuíasRecetas paso a paso para las formas comunes de usar Sypnia, desde apps hechas con constructores de IA y Next.js en Vercel hasta Supabase, source maps en CI, correos de alerta desde tu propio motor, y venir desde Sentry.ReferenciaLas páginas donde se consulta, desde el esquema de eventos y el glosario hasta lo planeado, el registro de cambios y las preguntas frecuentes.
↑↓ para moverte↵ para abrirEsc para cerrar