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
| Mensaje | Solució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: ns | Agrega ?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_NAMESPACE | Con 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 0 | Los 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íntoma | Causa |
|---|
401 missing or invalid bearer token | No hay header Authorization: Bearer …, o el token es desconocido. |
401 … or token not scoped to this namespace | Multi-tenant: la lista namespaces del token no incluye el namespace solicitado. |
403 this token is read-only; write queries are forbidden | Usa un token read-write para escrituras, DDL y endpoints de administración. |
| Un token revocado sigue funcionando por Bolt | Las sesiones Bolt single-tenant conservan la identidad con la que iniciaron sesión; cierra las conexiones. |
| Un token nuevo se rechaza durante unos segundos | El 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 log | Causa | Solución |
|---|
| Timeout del lock del writer | Una 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 larga | Mantén cortas las transacciones de escritura; revisa /v0/admin/queries. |
| Demasiadas consultas concurrentes | El control de admisión de lecturas estuvo lleno durante NAMIDB_QUERY_ADMISSION_WAIT_MS | Reintenta con backoff, o sube NAMIDB_MAX_CONCURRENT_QUERIES si la máquina tiene margen. |
memory_pressure | El 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 tope | Reintenta 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_capacity | Los pools de memoria de búsqueda son demasiado pequeños para la petición | Sube NAMIDB_SEARCH_INDEX_CACHE_MAX_BYTES / NAMIDB_SEARCH_WORKSPACE_MAX_BYTES. |
another backup or restore is already running | Se ejecuta un backup o restore por proceso | Reintenta 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
- 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:.
- Ancla los patrones en un nodo selectivo (una clave única o
_id) y
limita los caminos de longitud variable (*1..4, no *).
- 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.
- 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íntoma | Causa |
|---|
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 M | El índice vectorial exige su dimensión. Corrige el embedding o el índice. |
| Un nodo nunca aparece en un KNN por coseno | Su vector tiene magnitud cero; cosine_similarity es NULL para él. |
Una búsqueda vectorial retorna menos de k | Menos 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 query | Las llamadas a procedimientos (algo.*, search.*, db.*) deben iniciar la consulta; pasa las entradas como parámetros. |
Conexiones Bolt
| Error | Solución |
|---|
Failed to obtain connection towards 'WRITE' server | Usa 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.Unauthorized | Token incorrecto. El nombre de usuario se ignora; el token es la contraseña. |
Neo.ClientError.Security.Forbidden | Multi-tenant: el token no tiene alcance sobre la base de datos de la sesión. |
Neo.ClientError.Request.Invalid y la conexión se cierra | Un mensaje superó --bolt-max-message-bytes; envía lotes más pequeños. |
Los datos se ven mal
| Síntoma | Explicació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ón | Las relaciones son únicas por (type, start, end); la segunda reemplazó a la primera. |
keys(n) lista una propiedad que es NULL | SET n.p = null guarda un null explícito; usa REMOVE n.p. |
Los valores retornados después de un FOREACH parecen sin cambios | El 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.