Verificación y problemas habituales - Next.js
Un evento de prueba controlado
import { getRay } from '@dockcodes/dock-ray-next';
await getRay().captureMessage('Mensaje de control DockRay');Llama a esto desde una ruta temporal en un entorno de pruebas y bórrala en cuanto la prueba funcione - las llamadas siguientes consumen el cupo mensual. El mensaje debería aparecer en el panel, en la sección Errores del proyecto al que apunta el token, con el nombre del entorno conservado.
Problemas habituales
La clave privada acabó en el código del navegador
Si RAY_PRIVATE_KEY recibió el prefijo NEXT_PUBLIC_, Next la incrustó en el paquete de cliente en el primer build - eso significa que la clave ya es pública. Renombrar la variable no deshace la fuga: revócala en el panel y genera una nueva.
Los errores del middleware no se notifican
El middleware siempre es un paquete de edge. Importar desde el punto de entrada principal (@dockcodes/dock-ray-next) en lugar de /edge, o no envolver la función de middleware con withRayMiddleware, es la causa más habitual.
Un aviso desde edge no llega pese a una configuración correcta
Una invocación de edge puede congelarse en el momento en que la función devuelve un valor. El wrapper de edge espera su informe precisamente por eso - comprueba que el error pase realmente por withRayMiddleware o rayRequestError desde /edge, y no por un ray.report() propio sin esperar.
Los errores de JavaScript del navegador no llegan
La ruta siempre responde 202, haya aceptado el aviso o no - es intencionado, para que quien llama no aprenda nada sobre las barreras. Comprueba por separado: si NEXT_PUBLIC_RAY_JS_ERRORS=true está definido (un cambio exige un nuevo build, porque queda incrustado en el paquete en tiempo de compilación), si RayBrowserReporting está montado en el layout raíz, si app/api/ray/browser/route.ts tiene export const runtime = 'nodejs', y - lo más fácil de pasar por alto - si el servidor tiene siquiera RAY_TOKEN y RAY_PRIVATE_KEY definidos. Sin ellos la ruta sigue respondiendo 202, simplemente no reenvía nada.
Faltan transacciones
RAY_TRACES_SAMPLE_RATE vale 0 por defecto. El token y la clave por sí solos no activan la medición.
Un despliegue preview de Vercel se notifica como producción
VERCEL_ENV y VERCEL_GIT_COMMIT_SHA solo se usan cuando RAY_ENVIRONMENT y RAY_RELEASE no están definidos. Si en los ajustes del proyecto en Vercel se definió RAY_ENVIRONMENT=production para todos los entornos a la vez, la detección automática deja de funcionar y cada preview se notifica como producción.
Un mismo error se parte en muchas entradas
El panel agrupa por la huella sha256(token del proyecto + tipo + mensaje). Next añade etiquetas del contexto de la ruta, pero eso no cambia el tipo ni el mensaje - un identificador incrustado en el mensaje de la excepción sigue partiendo un error en mil filas.
El panel responde 200 pero no aparece el evento
Una respuesta 200 {"success": false} significa que la cuenta ha agotado su cupo mensual de errores. La integración no lo trata como una avería, y hace bien. El cupo se ve en el panel de la cuenta; hasta fin de mes se calcula a partir del consumo registrado, así que borrar errores no lo reinicia.
Sigue sin funcionar
Repasa la lista de comprobación de falta de datos y, si no ayuda, escríbenos. Indica el nombre del proyecto, la versión de la integración y la hora aproximada de la prueba: acorta el camino a la respuesta.