Saltearse al contenido

Solución de problemas

Empieza por el log del servidor (las líneas de arranque registran la configuración efectiva) y por GET /v0/health. Las respuestas de error llevan un code; consulta la taxonomía de errores.

El servidor no arranca

MensajeSolución
no auth configured: set --auth-token / NAMIDB_AUTH_TOKEN or --auth-tokens-file, or pass --no-auth …Configura un token o un archivo de tokens. --no-auth solo para desarrollo local.
invalid --store: failed to open backend for 'file:///var/lib/namidb?ns=prod': … Permission denied (os error 13)El usuario del contenedor (uid 65532) no puede escribir el directorio. Usa un volumen con nombre, o haz chown -R 65532:65532 del directorio del host montado con bind mount.
URI '…' is missing required parameter: nsAgrega ?ns=<namespace> (no hace falta con --multi-tenant).
bad namespace '…': … must start with [a-z0-9]Usa un nombre válido: letras minúsculas, dígitos, -, _.
NAMIDB_MEMORY_MAX_BYTES=auto requires a finite cgroup memory limit …Dale al contenedor un límite de memoria, o define una cantidad exacta de bytes.
NAMIDB_CACHE_MAX_BYTES must be an exact non-negative byte count …Las variables en bytes aceptan enteros simples (1073741824), no 1GB.
Un error sobre NAMIDB_RANGE_CACHE_NAMESPACECon NAMIDB_NVME_CACHE_PATH, define también NAMIDB_NVME_CACHE_MAX_BYTES y un NAMIDB_RANGE_CACHE_NAMESPACE estable.
NAMIDB_RESTORE_POINT_RETENTION needs the background maintenance loop: set NAMIDB_COMPACTION_INTERVAL above zero, or the retention to 0Los puntos de restauración necesitan el mantenimiento: deja --compaction-interval mayor que cero o desactiva la retención.
the HTTP request ceiling is at or below a query budget … (advertencia)Sube --http-request-timeout por encima de --query-timeout y --write-timeout, o déjalo sin definir.

Autenticación

SíntomaCausa
401 missing or invalid bearer tokenNo hay header Authorization: Bearer …, o el token es desconocido.
401 … or token not scoped to this namespaceMulti-tenant: la lista namespaces del token no incluye el namespace solicitado.
403 this token is read-only; write queries are forbiddenUsa un token read-write para escrituras, DDL y endpoints de administración.
Un token revocado sigue funcionando por BoltLas sesiones Bolt single-tenant conservan la identidad con la que iniciaron sesión; cierra las conexiones.
Un token nuevo se rechaza durante unos segundosEl archivo de tokens se recarga cada --auth-tokens-reload-interval (10 s).

/v0/health retorna 503

El cuerpo dice por qué:

  • writer: "degraded" con un writer_error. Normalmente otro proceso abrió el namespace para escritura y bloqueó a este: un segundo servidor, un namidb run --store … de la CLI, un servidor MCP o un cliente de Python con escritura sobre el mismo store. El epoch de /v0/health aumenta cada vez que se reclama el namespace. Asegúrate de que exactamente un proceso escriba cada namespace; abre los lectores de Python adicionales con read_only=True. Con el valor por defecto --fence-policy steal, el servidor recupera el namespace por sí solo; con yield queda degradado hasta que se reinicia.
  • memory_pressure: true. El proceso llegó a --memory-max-bytes. Consulta Memoria y cachés.

Las peticiones fallan con 503

Cuerpo o logCausaSolución
Timeout del lock del writerUna escritura esperó más de --writer-lock-timeout (30 s), normalmente detrás de una transacción de escritura Bolt larga o de una sentencia masiva largaMantén cortas las transacciones de escritura; revisa /v0/admin/queries.
Demasiadas consultas concurrentesEl control de admisión de lecturas estuvo lleno durante NAMIDB_QUERY_ADMISSION_WAIT_MSReintenta con backoff, o sube NAMIDB_MAX_CONCURRENT_QUERIES si la máquina tiene margen.
memory_pressureEl proceso está en --memory-max-bytes cuando llega la sentencia o, mientras se ejecuta, el pool compartido de consultas (75% del tope) está lleno o el proceso llega al topeReintenta con backoff. Si se repite: ejecuta menos consultas grandes a la vez, asegúrate de que los clientes Bolt consuman o cierren sus resultados, baja los tamaños de caché, sube el límite del contenedor junto con el tope, o haz flush (POST /v0/admin/flush). Ver el presupuesto por consulta.
search_index_cache_capacity, search_workspace_capacityLos pools de memoria de búsqueda son demasiado pequeños para la peticiónSube NAMIDB_SEARCH_INDEX_CACHE_MAX_BYTES / NAMIDB_SEARCH_WORKSPACE_MAX_BYTES.
another backup or restore is already runningSe ejecuta un backup o restore por procesoReintenta más tarde.

Un backup con as_of también puede fallar con 404 restore_point_unavailable (el instante es anterior a la ventana de puntos de restauración, cuyos límites trae el cuerpo), 400 as_of_in_future (posterior al reloj del servidor) o 400 invalid_as_of.

Los drivers de Neo4j los reintentan automáticamente (llegan como Neo.TransientError.*).

Timeouts, límites de filas y escrituras grandes

  • 504 timeout en una lectura. La sentencia superó --query-timeout. Revisa su plan con EXPLAIN, agrega un índice o una restricción sobre la clave filtrada, o sube el presupuesto. Desde 3.3.0 cada operador revisa el deadline, así que un producto cartesiano o un ordenamiento grande que antes seguía mucho más allá del presupuesto ahora se detiene en él.
  • 504 en una escritura masiva. Las escrituras tienen --write-timeout (60 s). Divide la carga en lotes UNWIND $rows de algunos miles de filas, o define NAMIDB_WRITE_TIMEOUT=0s mientras dure la carga. Una escritura que agota el tiempo no confirma nada.
  • 413 row_cap. Un operador materializaría más de --query-row-cap filas (1.000.000). Suele ser una condición de join faltante o un patrón de longitud variable sin límite; si no, pagina el resultado.
  • 413 query_memory_limit. La sentencia necesita más memoria de trabajo de la que permite --query-memory-max-bytes (por defecto, la mitad de --memory-max-bytes). Falla igual en cada ejecución, así que reintentar no ayuda, y una escritura que lo recibe no confirma nada. Retorna menos filas (LIMIT, paginación con ORDER BY … SKIP … LIMIT o un rango de claves), retorna menos columnas o columnas más angostas, y agrega en la consulta en lugar de retornar filas crudas o juntarlas con collect(). Sube el presupuesto solo si la consulta es legítima y el tope y el límite del contenedor tienen margen; ver Memoria.
  • 413 en la propia petición. El cuerpo HTTP supera 2 MiB; envía lotes más pequeños.
  • 408. La petición completa superó --http-request-timeout.

Consultas lentas

  1. Ejecuta EXPLAIN sobre ella. Un NodeScan con predicates=[…] sobre un label grande significa que ningún índice sirve el filtro; declara uno (Esquema). Una búsqueda por índice aparece como NodeByPropertyValue con una línea # route:.
  2. Ancla los patrones en un nodo selectivo (una clave única o _id) y limita los caminos de longitud variable (*1..4, no *).
  3. Después de una carga masiva, ejecuta POST /v0/admin/compact: un nivel 0 profundo hace que cada lectura toque muchos archivos. namidb_compaction_l0_backlog_ssts muestra la profundidad.
  4. Revisa el log de consultas lentas (--slow-query-threshold, por defecto 1 s) y el histograma namidb_query_duration_seconds.

Sorpresas en la búsqueda

SíntomaCausa
CREATE VECTOR INDEX falla con “built without the vector-index feature”Al binario le falta la feature: los archivos de la CLI y de MCP, o un servidor compilado desde el código fuente sin --features vector-index,text-index. Usa la imagen, el servidor del release, el wheel de Python, o vuelve a compilar.
Una escritura falla con embedding has dim N but vector index … declares MEl índice vectorial exige su dimensión. Corrige el embedding o el índice.
Un nodo nunca aparece en un KNN por cosenoSu vector tiene magnitud cero; cosine_similarity es NULL para él.
Una búsqueda vectorial retorna menos de kMenos de k nodos coinciden con el label y el filter.
does not recognise the option …Un error de tipeo en una opción de un procedimiento; el mensaje lista las válidas.
CALL must be the first clause in a queryLas llamadas a procedimientos (algo.*, search.*, db.*) deben iniciar la consulta; pasa las entradas como parámetros.

Conexiones Bolt

ErrorSolución
Failed to obtain connection towards 'WRITE' serverUsa bolt:// (o bolt+s://), no neo4j://: no se sirven tablas de enrutamiento.
UnsupportedServerProduct / “does not identify as a genuine Neo4j”Un cliente bolt:// en texto plano contra un listener TLS, o NAMIDB_BOLT_SERVER_AGENT definido con un valor que no es de Neo4j para un cliente estricto.
Neo.ClientError.Security.UnauthorizedToken incorrecto. El nombre de usuario se ignora; el token es la contraseña.
Neo.ClientError.Security.ForbiddenMulti-tenant: el token no tiene alcance sobre la base de datos de la sesión.
Neo.ClientError.Request.Invalid y la conexión se cierraUn mensaje superó --bolt-max-message-bytes; envía lotes más pequeños.

Los datos se ven mal

SíntomaExplicación
Las fechas vuelven por HTTP como números del tipo "20758"HTTP serializa DATE como días desde 1970-01-01. Retorna toString(d).
Un segundo CREATE (a)-[:T]->(b) no agregó una relaciónLas relaciones son únicas por (type, start, end); la segunda reemplazó a la primera.
keys(n) lista una propiedad que es NULLSET n.p = null guarda un null explícito; usa REMOVE n.p.
Los valores retornados después de un FOREACH parecen sin cambiosEl RETURN después de FOREACH muestra la fila como estaba antes; vuelve a leer en una consulta nueva.
Un proceso nuevo no ve datos en memory://Cada store memory:// es privado del Client (o proceso) que lo abrió.

El disco no deja de crecer

  • El historial reciente es normal. Cada commit escribe un manifest y un puntero pequeños; el sweep los recupera solo después de --sweep-min-age (24 h).
  • ¿Mantenimiento desactivado? Con --compaction-interval 0s no se compacta ni se hace sweep de nada; con --sweep-delete false el sweep solo registra.
  • La retención de puntos de restauración conserva a propósito lo que el namespace escribe durante la ventana. El sweep registra restore_window_retained y restore_window_bytes; acorta --restore-point-retention o ponla en 0 si el historial cuesta más de lo que vale.
  • Python embebido hace sweep solo después de compactaciones aplicadas; llama a sweep() después de cargas grandes, y a sweep(min_age_secs=0) si ningún otro proceso lee el namespace.
  • Las cargas multipart incompletas en stores compatibles con S3 las conserva el bucket; agrega una regla de ciclo de vida que las aborte.
  • El spool (NAMIDB_SPOOL_DIR) necesita unas tres veces los datos de nodos compactados durante una compactación grande, y luego se vacía.

Obtener ayuda

Reúne la versión del servidor (/v0/version), el log de arranque, la sentencia que falla con EXPLAIN y el cuerpo de /v0/health. Reporta los bugs del motor en github.com/namidb/namidb/issues; escribe a info@namidb.com para soporte comercial.