# 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: el motor de Sypnia (código abierto, en tu propia infraestructura) y Sypnia Cloud (servicio pago). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/sdks/troubleshooting/

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:

```bash
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é ves                                                                         | Causa                                                                                                                                                                                                   | Qué hacer                                                                                                    |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Ninguna petición, y `[sypnia] off: no project`                                  | `project` 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 out`                                   | `localStorage` 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: disabled`                                    | `enabled: false`.                                                                                                                                                                                       | Revisa la condición que pasas.                                                                               |
| Ninguna petición solo en algunas páginas                                        | La ruta está en `ignoreRoutes`.                                                                                                                                                                         | Quítala de la lista.                                                                                         |
| Ninguna línea en la consola                                                     | `init` 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_CLIENT`                          | Un 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-Policy`               | La política de tu sitio no permite la dirección.                                                                                                                                                        | Mira la sección Política de seguridad de contenido.                                                          |
| `401 unauthorized`                                                              | La 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_credential`                                                          | Se 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_allowed`                                                        | El proyecto lista orígenes permitidos y el de esta página no está.                                                                                                                                      | Mira la sección Orígenes y CORS.                                                                             |
| `413 payload_too_large`                                                         | No viene del SDK: mantiene los lotes muy por debajo del límite. Un proxy intermedio está reescribiendo el cuerpo.                                                                                       | Revisa el proxy.                                                                                             |
| `429 rate_limited`                                                              | Una 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](https://docs.sypnia.com/es/sdks/sampling-and-quotas).                               |
| `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](https://docs.sypnia.com/es/reference/event-schema). | Repórtalo con el evento que imprime `debug`.                                                                 |
| `200`, nada descartado, nada en Sypnia                                          | Entorno 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 certificado | `endpoint` 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é ves                                                 | Causa                                                              | Qué hacer                                                          |
| ------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ |
| No se imprime ningún `server_request` con `debug: true` | `init` 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 failed`              | El 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 serverless                       | La función se congeló antes del envío.                             | Usa `wrapFetchHandler`, o `await flush()` antes de devolver.       |
| Solo algunas rutas                                      | Los 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:

```bash
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`

```ts
const nextConfig: NextConfig = {
  async rewrites() {
    return [{ source: '/_sy/:path*', destination: 'https://ingest.sypnia.com/:path*' }];
  },
};
```

`instrumentation-client.ts`

```ts
init({ endpoint: '/_sy' });
```

**nginx**

`nginx.conf`

```nginx
location /_sy/ {
  proxy_pass https://ingest.sypnia.com/;
  proxy_set_header Host ingest.sypnia.com;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_ssl_server_name on;
}
```

`src/main.ts`

```ts
init({ project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e', 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.

| Directiva     | Agrega                      | Hace falta para                                               |
| ------------- | --------------------------- | ------------------------------------------------------------- |
| `connect-src` | `https://ingest.sypnia.com` | Enviar eventos y grabaciones.                                 |
| `script-src`  | `https://ingest.sypnia.com` | Solo 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`.

| Revisa                                                            | Cómo                                                                                                                                                                            | Arreglo                                                              |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| 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.

| Causa                                                                                                                                         | Cómo saberlo                                                                                                                     | Qué 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](https://docs.sypnia.com/es/sdks/sampling-and-quotas).
- 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](https://docs.sypnia.com/es/cloud/support) para Sypnia Cloud y en [Contribuir](https://docs.sypnia.com/es/licensing/contributing) para el motor de código abierto.
