Notas de diagnóstico para los problemas que los operadores encuentran con más frecuencia. Cada sección describe el síntoma, la causa y la solución. Para la superficie completa de flags y variables de entorno, consulta la referencia de CLI y la configuración.
El motor no arranca
Fallo en la generación del certificado TLS
Síntoma: el motor termina al arrancar con un error de escritura que referencia el directorio de datos.
Si no se proporcionan --tls-cert/--tls-key, el motor genera un certificado
autofirmado en el directorio de datos antes de que ningún listener acepte una conexión.
Si el directorio de datos es de solo lectura o no existe, la escritura falla y el
proceso termina.
Solución: asegúrate de que la ruta indicada por --data-dir (o OLIVARES_DATA_DIR,
con valor por defecto ./olivares-data) apunte a un directorio escribible y
persistente. Alternativamente, proporciona tu propio certificado con --tls-cert y
--tls-key para que no se intente la generación.
El rol de Postgres es privilegiado
Síntoma: el motor termina con un mensaje sobre un rol superuser o BYPASSRLS.
El almacén Postgres aplica el aislamiento de tenants con FORCE ROW LEVEL SECURITY.
Un rol superuser o BYPASSRLS evita silenciosamente todas las políticas RLS, por lo
que el motor rechaza arrancar contra uno de estos roles.
Solución: provisiona un rol dedicado con privilegios mínimos (NOSUPERUSER NOBYPASSRLS NOCREATEROLE NOCREATEDB) que sea propietario de su base de datos. Si realmente
necesitas saltarte esta protección en un entorno de un solo tenant o desechable, pasa
--allow-privileged-db-role. Consulta self-host para
la configuración completa de Postgres.
—seed-demo en un bind que no es loopback
Síntoma: el motor termina con un error que te indica enlazar a 127.0.0.1.
--seed-demo provisiona un administrador de demo cuya contraseña es pública (está en
el árbol de código fuente). El motor rechaza arrancar si --listen o --grpc-listen
están enlazados a una dirección que no sea loopback.
Solución: enlaza a loopback (127.0.0.1) o elimina --seed-demo. El modo demo es
solo para pruebas locales — consulta el quickstart.
Directorio de datos inexistente o sin permisos de escritura
Síntoma: el motor termina referenciando una ruta inexistente o un error de permisos.
El directorio de datos contiene el almacén SQLite (cuando se usa el motor por defecto), la clave de firma de auditoría y el material TLS. Debe existir y ser escribible antes del arranque.
Solución: crea el directorio con permisos restrictivos y apunta --data-dir o
OLIVARES_DATA_DIR a él. Para despliegues en contenedores, monta un volumen
persistente.
Las fuentes no producen aristas
OLIVARES_SOURCES_CONFIG no está definida
Síntoma: el motor arranca, el log de arranque advierte de que no hay fuentes configuradas y el mapa de acceso permanece vacío.
Sin OLIVARES_SOURCES_CONFIG el motor funciona sin conectores de fuentes. No se
produce un crash — advierte de forma honesta y continúa.
Solución: establece OLIVARES_SOURCES_CONFIG con la ruta de tu fichero JSON de
fuentes. Consulta connect a source.
JSON inválido en el fichero de configuración
Síntoma: el log de arranque advierte de una configuración ilegible o inválida; no se registra ninguna fuente.
El motor advierte y continúa con una lista de fuentes vacía ante cualquier error de parseo de JSON. No aborta el arranque.
Solución: valida el fichero con jq . < "$OLIVARES_SOURCES_CONFIG" y corrige
cualquier error de sintaxis. Relee el log de arranque del motor — la advertencia
incluye el error de parseo.
Cadena de tipo de fuente incorrecta
Síntoma: una fuente configurada no resuelve; el log de arranque advierte de que el tipo es desconocido.
Los tipos de fuente registrados son cadenas exactas: pgaudit, s3cloudtrail, ebpf,
runtime, mcp, claude. La documentación anterior que usaba pg_audit o
cloudtrail era incorrecta — esas cadenas no resuelven.
Solución: usa los valores exactos de kind listados arriba. Si falta un tipo que
esperas, puede que aún no esté conectado al binario estándar de serve. Confróntalo
con el descriptor del propio conector.
Fichero de log no legible
Síntoma: la fuente se registra pero no emite observaciones; el log reporta un error de permisos o fichero no encontrado.
El conector pgaudit lee el fichero de log de PostgreSQL; el conector s3cloudtrail lee ficheros de log de CloudTrail o un directorio de ellos. Ambos requieren acceso de lectura desde el proceso que ejecuta el motor o el collector.
Solución: comprueba los permisos del valor log_path (pgaudit) o path
(s3cloudtrail). Para despliegues en contenedores, verifica que el montaje del volumen es
correcto y que el fichero existe en la ruta esperada dentro del contenedor.
pgaudit follow con formato csvlog
Síntoma: una fuente pgaudit con "follow": "true" y "format": "csvlog" no hace
seguimiento continuo — se ejecuta como un batch.
follow solo funciona con jsonlog. Un fichero csvlog siempre se lee como batch
porque sus registros pueden abarcar varias líneas, lo que hace que el seguimiento
continuo no sea seguro.
Solución: cambia el formato de log de PostgreSQL a jsonlog si necesitas seguimiento
continuo. En caso contrario, acepta el comportamiento de batch y, opcionalmente,
establece poll_seconds en la entrada de la fuente para controlar la frecuencia de
relectura.
Los hooks de Claude Code no se disparan
Managed settings no desplegados
Síntoma: Claude Code se ejecuta sin interposición de hooks; las llamadas a herramientas no se observan ni se gobiernan.
Los hooks de enforcement se distribuyen en la capa de managed-settings empresariales de Claude Code. Si el fichero de managed-settings no está presente en el host, los hooks simplemente están ausentes.
Solución: verifica que el fichero de managed-settings está desplegado en la ruta correcta en cada host donde se ejecuta Claude Code. Con managed-hooks-only activado, un desarrollador no puede desactivar ni reemplazar el hook desde un fichero de settings de menor precedencia.
Sobreescritura de ANTHROPIC_BASE_URL
Síntoma: los hooks están desplegados pero Claude Code los ignora por completo.
Un ANTHROPIC_BASE_URL personalizado puede saltarse los server-managed-settings, lo que
implica que los managed hooks nunca se cargan. Esta es una limitación honesta y
documentada de la vía cooperativa — el conector no puede hacer enforcement contra un
cliente que opta por no usar la capa de settings.
Solución: asegúrate de que ANTHROPIC_BASE_URL no esté definida, o de que el
endpoint personalizado siga respetando los managed settings. Para agentes no
cooperativos, el respaldo kernel/eBPF es la fuente de verdad, no los hooks.
Hook PEP inalcanzable
Síntoma: todas las llamadas a herramientas se deniegan; el hook devuelve un deny limpio para cada petición.
El PEP es deny-closed: si el punto de enforcement es inalcanzable — partición de red, dirección incorrecta, proceso caído — cada llamada a herramienta se deniega. El valor cero del veredicto es en sí mismo un deny. Esto es un diseño deliberado de riesgo asimétrico.
Solución: comprueba la conectividad loopback a la dirección del PEP. Verifica que el
motor está en ejecución y que el listener HTTP está sano (/livez). Si el PEP está
intencionadamente caído, el modo de enforcement local más ligero (sin ida y vuelta al
motor) evita bloquear a los desarrolladores mientras el plano de control está offline,
pero debe configurarse de forma explícita.
Fallos en la verificación de la cadena de auditoría
Discrepancia de clave
Síntoma: olivares audit verify termina con código distinto de cero; el informe
muestra un fallo de verificación de firma.
El flag --pubkey o --event-pubkey apunta a una clave pública que no corresponde con
la clave de firma que escribió los checkpoints. Esto es habitual tras una rotación de
claves o cuando se verifica contra la copia incorrecta de la clave fuera del servidor.
Solución: usa la clave pública que corresponde a la clave de firma activa durante el periodo que estás verificando. El motor registra la huella digital de la clave al arrancar.
Hueco en la cadena tras reemplazo del directorio de datos
Síntoma: olivares audit verify reporta un hueco en la cadena — los extremos de
cadena almacenados no coinciden con las entradas del ledger.
Si el directorio de datos fue reemplazado (por ejemplo, restaurado desde un snapshot de
sistema de ficheros en lugar de olivares dr restore), los extremos de la cadena pueden
no alínearse con el ledger.
Solución: usa olivares dr verify para un simulacro de DR no destructivo que
verifica la continuidad del ledger tras una restauración. olivares dr restore es la
vía de restauración segura para la continuidad del ledger — re-verifica la cadena al
restaurar y termina con código distinto de cero a menos que el ledger esté correcto.
Múltiples nodos con claves de firma distintas
Síntoma: el ledger se bifurca en el failover; la verificación pasa con los checkpoints de un nodo pero falla con los del otro.
En un clúster activo-pasivo, cada nodo genera su propia clave de firma en el primer arranque si no se comparte ninguna. Tras el failover, el nuevo líder firma con una clave diferente, bifurcando la cadena.
Solución: comparte la clave de firma entre réplicas mediante
OLIVARES_AUDIT_SIGNING_KEY_FILE (un secreto montado) u
OLIVARES_AUDIT_SIGNING_KEY (base64 inline, menos recomendable). Consulta la
referencia de configuración para la custodia de claves.
Problemas con las sondas de salud
/readyz devuelve 503 con “store”:“down”
Síntoma: la sonda de readiness falla; el cuerpo incluye "store":"down".
El ping al almacén se ejecutó con un timeout corto y falló. La instancia drena en lugar de quedarse colgada esperando a un backend bloqueado.
Solución: comprueba la conectividad con la base de datos. Para Postgres, verifica el DSN, la ruta de red y que el proceso de la base de datos está en ejecución. Para SQLite, comprueba que el fichero del almacén en el directorio de datos no está bloqueado ni corrupto.
/readyz devuelve 503 con “leader”:false
Síntoma: la sonda de readiness devuelve 503; el cuerpo incluye
"leader":false.
Esto es esperado en un clúster activo-pasivo. Un standby reporta 503 en /readyz para
que el balanceador de carga deje de enrutar tráfico hacia él, sin reiniciarlo. Cuando el
líder cae, el standby adquiere el liderazgo y /readyz pasa a devolver 200.
Solución: no se necesita acción — este es el comportamiento correcto. Asegúrate de que
tu balanceador de carga enruta basándose en /readyz (readiness) y tu orquestador
reinicia basándose en /livez (liveness). No confundas ambas o tendrás bucles de
reinicio en un standby sano.
/livez falla
Síntoma: la sonda de liveness devuelve un error o supera el timeout.
/livez no ejecuta ninguna comprobación de dependencias. Si falla, el propio proceso
está en mal estado — no es una dependencia downstream.
Solución: comprueba los recursos del sistema (memoria, disco, descriptores de fichero)
y los logs del motor. Un reinicio es apropiado aquí, a diferencia de un fallo en
/readyz.
Problemas del modo demo
Las credenciales de demo son públicas
La contraseña del administrador de demo está en el árbol de código fuente a propósito —
no es un secreto. Usa siempre un directorio de datos desechable con --seed-demo y
nunca expongas el demo a la red.
Transición de demo a producción
No reútilices un directorio de datos de demo. El demo genera datos fabricados y una
credencial pública. Empieza de cero: ejecuta olivares serve sin --seed-demo,
reclama el token de configuración inicial y crea un administrador real. Consulta
self-host.
Problemas de configuración del PDP
Fichero de políticas Cedar inválido
Síntoma: el log de arranque advierte de que el PDP externo está desactivado; el motor continúa solo con ABAC y RBAC nativos.
Si OLIVARES_PDP_ENGINE=cedar pero OLIVARES_PDP_CEDAR_FILE apunta a un fichero
ilegible o malformado, el motor desactiva el PDP externo. No produce un crash y no deja
las peticiones sin gobernar — el motor nativo sigue aplicando las políticas.
Solución: comprueba la ruta del fichero y valida la sintaxis de la política Cedar. El log de arranque incluye el error específico.
Endpoint OPA inalcanzable
Síntoma: igual que el anterior — PDP externo desactivado, RBAC nativo sigue gobernando.
Si OLIVARES_PDP_ENGINE=opa pero OLIVARES_PDP_OPA_URL es inalcanzable o devuelve
errores, el motor recurre al enforcement nativo. Un PDP externo roto nunca abre la
puerta.
Solución: verifica la URL de OPA, la ruta de red y el bearer token
(OLIVARES_PDP_OPA_TOKEN). Confirma que el servicio OPA está en ejecución y que la ruta
de decisión (OLIVARES_PDP_OPA_PATH) es correcta.
Ambos motores PDP configurados
Síntoma: evaluación de políticas inesperada; no queda claro qué motor está activo.
OLIVARES_PDP_ENGINE selecciona exactamente un motor: cedar u opa. Configurar
variables conflictivas para ambos motores junto con un selector de motor ambiguo o
ausente conduce a un estado impredecible del PDP.
Solución: establece OLIVARES_PDP_ENGINE con exactamente un valor y configura solo
las variables de ese motor. Elimina las variables de entorno del otro motor para evitar
confusión.
Relacionado
- CLI reference — superficie completa de flags para
serve,auditydr. - Configuration — variables de entorno y selección de almacén.
- Self-host — guía de instalación en producción.
- Connect a source — cableado de fuentes y claves de configuración.