Technical manualManual técnico › Operation › When something fails › TroubleshootingOperación › Cuando algo falla › Solución de problemas

Troubleshooting

Solución de problemas

The errors an operator really meets, with their cause and what to do. Start by reading the end of the log of backend: almost every start-up problem is explained there in words.

Los errores con los que un operador se encuentra de verdad, con su causa y qué hacer. Empezá por leer el final del registro de backend: casi todos los problemas de arranque están explicados ahí con palabras.

👤 Who: System administrator📍 Where: Server console

👤 Quién: Administrador de sistemas📍 Dónde: Consola del servidor

First, locate the problem

Primero, ubicá el problema

Is every container running? docker compose -f docker-compose.<edition>.yml ps. A backend that restarts again and again has a start-up problem.
Does the application answer? curl http://localhost:8222/actuator/health.
What does the log say? docker compose -f docker-compose.<edition>.yml logs backend, from the end backwards.
Is it for everybody or for one organisation? For everybody, look at the installation. For one organisation or one user, look at its modules, its state and the role of the user.

¿Están corriendo todos los contenedores? docker compose -f docker-compose.<edición>.yml ps. Un backend que se reinicia una y otra vez tiene un problema de arranque.
¿Contesta la aplicación? curl http://localhost:8222/actuator/health.
¿Qué dice el registro? docker compose -f docker-compose.<edición>.yml logs backend, desde el final hacia atrás.
¿Le pasa a todos o a una organización? Si es a todos, mirá la instalación. Si es a una organización o a un usuario, mirá sus módulos, su estado y el rol del usuario.

The application does not start

La aplicación no arranca

Message in the log	Cause	What to do
A box titled CRITICAL SECURITY CONFIGURATION ERROR	PMS_SECURITY_JWT_SECRET or PMS_SECURITY_TOTP_ENCRYPTION_KEY is missing, shorter than 32 characters or a sample value.	Generate both as the box itself says and put them in .env.
A box titled WORKFLOW SECRET KEY CONFIGURATION ERROR	KUBRIK_WORKFLOW_SECRET_KEY is missing, is not 32 bytes in Base64 or is a sample value; or its name is empty.	Generate it with openssl rand -base64 32.
Configured currentVersion=1 has no matching key in kserp.credentials.master-keys.keys	The application did not receive KSERP_MASTER_KEY_V1. It is only read when SPRING_PROFILES_ACTIVE includes prod.	Set both variables.
Master key v1 must decode to exactly 32 bytes	The master key is not 32 bytes in Base64.	Generate it with openssl rand -base64 32. Do not replace a key that already protects data.
Could not resolve placeholder and a name	A required variable has no value.	Set the variable that the message names.
No qualifying bean of type followed by a name that ends in IFileStorageStrategy	MINIO_S3_PROVIDER is empty or is neither minio nor s3.	Set it, with the other file store variables.
app.mail.transport=… requires …	The mail transport sends for real and something it needs is empty.	Set what the message names, or use log for the time being.
Connection refused or password authentication failed with the name of the database	The database is not reachable, or the user or the password is wrong.	See the next section.
Migration checksum mismatch or the name of a migration followed by an error	A change to the database could not be applied.	See Upgrading to a new version.

Mensaje en el registro	Causa	Qué hacer
Un recuadro titulado CRITICAL SECURITY CONFIGURATION ERROR	Falta PMS_SECURITY_JWT_SECRET o PMS_SECURITY_TOTP_ENCRYPTION_KEY, tiene menos de 32 caracteres o es un valor de ejemplo.	Generá las dos como dice el propio recuadro y ponelas en .env.
Un recuadro titulado WORKFLOW SECRET KEY CONFIGURATION ERROR	Falta KUBRIK_WORKFLOW_SECRET_KEY, no son 32 bytes en Base64 o es un valor de ejemplo; o su nombre está vacío.	Generala con openssl rand -base64 32.
Configured currentVersion=1 has no matching key in kserp.credentials.master-keys.keys	La aplicación no recibió KSERP_MASTER_KEY_V1. Solo se lee cuando SPRING_PROFILES_ACTIVE incluye prod.	Definí las dos variables.
Master key v1 must decode to exactly 32 bytes	La clave maestra no son 32 bytes en Base64.	Generala con openssl rand -base64 32. No reemplaces una clave que ya protege datos.
Could not resolve placeholder y un nombre	Una variable obligatoria no tiene valor.	Definí la variable que nombra el mensaje.
No qualifying bean of type seguido de un nombre que termina en IFileStorageStrategy	MINIO_S3_PROVIDER está vacío o no es ni minio ni s3.	Definilo, junto con las demás variables del almacén.
app.mail.transport=… requires …	El transporte de correo envía de verdad y algo que necesita está vacío.	Definí lo que nombra el mensaje, o usá log por el momento.
Connection refused o password authentication failed con el nombre de la base	No se llega a la base de datos, o el usuario o la contraseña están mal.	Mirá la sección siguiente.
Migration checksum mismatch o el nombre de una migración seguido de un error	No se pudo aplicar un cambio a la base de datos.	Mirá Actualizar a una versión nueva.

It cannot connect to the database or to the cache

No se conecta a la base de datos o a la caché

Check the two services. docker compose -f docker-compose.<edition>.yml ps must show postgres and redis as healthy. The application waits for both before starting.
Check the addresses. Inside Compose, the application reaches them by service name and internal port: postgres:5432 and redis:6379. The ports 5444 and 6355 are the ones published on the server, for tools that run outside.
Check the three passwords. POSTGRES_PASSWORD, SPRING_R2DBC_PASSWORD and SPRING_FLYWAY_PASSWORD must be the same value.
A password changed after the first start is not applied to the database. PostgreSQL sets the password only when it creates its volume. Change it inside the database as well, or go back to the original value.
The cache is not optional. Real-time notifications and the progress of background jobs depend on it.

Revisá los dos servicios. docker compose -f docker-compose.<edición>.yml ps tiene que mostrar postgres y redis como sanos. La aplicación espera a los dos antes de arrancar.
Revisá las direcciones. Dentro de Compose, la aplicación llega a ellos por nombre de servicio y puerto interno: postgres:5432 y redis:6379. Los puertos 5444 y 6355 son los publicados en el servidor, para herramientas que corren afuera.
Revisá las tres contraseñas. POSTGRES_PASSWORD, SPRING_R2DBC_PASSWORD y SPRING_FLYWAY_PASSWORD tienen que ser el mismo valor.
Una contraseña cambiada después del primer arranque no se aplica a la base. PostgreSQL fija la contraseña solo cuando crea su volumen. Cambiala también dentro de la base, o volvé al valor original.
La caché no es opcional. Las notificaciones en tiempo real y el avance de los trabajos en segundo plano dependen de ella.

Files and images

Archivos e imágenes

What you see	Cause	What to do
Could not verify/create MinIO bucket in the log	The file store did not answer at start-up, or the user or password is wrong.	Check MINIO_S3_ENDPOINT, STORAGE_ACCESS_KEY and STORAGE_SECRET_KEY, and that the file store is running.
Uploads work but images are not shown	The download links carry an address the browser cannot open.	Publish the file store under an address the users reach and put it in MINIO_S3_ENDPOINT.
Images stopped showing after a restore	The file store was not restored along with the database.	See Backups and restore.
Every upload fails	The file store is full, stopped or refusing the user.	Check its own log and its free disk.

Qué ves	Causa	Qué hacer
Could not verify/create MinIO bucket en el registro	El almacén no contestó al arrancar, o el usuario o la contraseña están mal.	Revisá MINIO_S3_ENDPOINT, STORAGE_ACCESS_KEY y STORAGE_SECRET_KEY, y que el almacén esté corriendo.
Las subidas funcionan pero las imágenes no se ven	Los enlaces de descarga llevan una dirección que el navegador no puede abrir.	Publicá el almacén bajo una dirección a la que lleguen los usuarios y ponela en MINIO_S3_ENDPOINT.
Las imágenes dejaron de verse después de una restauración	El almacén no se restauró junto con la base.	Mirá Copias de seguridad y restauración.
Fallan todas las subidas	El almacén está lleno, detenido o rechazando al usuario.	Revisá su propio registro y su disco libre.

Errors the application answers

Errores que contesta la aplicación

Error	Cause	What to do
401	The session ended or the user is not signed in.	Sign in again. If it happens to everybody at once, PMS_SECURITY_JWT_SECRET changed.
403	The role of the user does not allow that operation.	Review the roles of the user in the organisation.
403 with TENANT_NOT_ACTIVE and the text "This workspace is not active. Contact your administrator."	The organisation is not active: it was never verified, or it was suspended.	Complete the e-mail verification, or have a platform administrator reactivate it.
409 with MODULE_DISABLED	The module is off for that organisation, or its plan does not include it. Only with PMS_GATING_ENABLED on.	Turn the module on; see Modules of an organisation.
409 with MODULE_READ_ONLY	The module is in read-only mode for that organisation: it can be consulted but not changed.	Have a platform administrator enable it fully.
402 with EDITION_REQUIRED	An older edition check was switched on by hand. It is off in a normal installation.	Remove the setting pms.edition-gate.enabled.

Error	Causa	Qué hacer
401	La sesión terminó o el usuario no ingresó.	Ingresar de nuevo. Si les pasa a todos a la vez, cambió PMS_SECURITY_JWT_SECRET.
403	El rol del usuario no permite esa operación.	Revisar los roles del usuario en la organización.
403 con TENANT_NOT_ACTIVE y el texto «This workspace is not active. Contact your administrator.»	La organización no está activa: nunca se verificó, o fue suspendida.	Completar la verificación por correo, o que un administrador de plataforma la reactive.
409 con MODULE_DISABLED	El módulo está apagado para esa organización, o su plan no lo incluye. Solo con PMS_GATING_ENABLED prendido.	Activar el módulo; mirá Módulos de una organización.
409 con MODULE_READ_ONLY	El módulo está en solo lectura para esa organización: se puede consultar pero no cambiar.	Que un administrador de plataforma lo habilite por completo.
402 con EDITION_REQUIRED	Alguien prendió a mano un control de edición anterior. En una instalación normal está apagado.	Sacar el ajuste pms.edition-gate.enabled.

ℹ️

After PMS_GATING_ENABLED is turned on, a module that was just enabled may keep answering 409 for up to a minute, until the application reads its state again.Con PMS_GATING_ENABLED prendido, un módulo recién activado puede seguir contestando 409 hasta un minuto, hasta que la aplicación vuelve a leer su estado.

Common issues

Problemas habituales

The administration app shows an error page instead of the sign-in screen: Its optional settings file is wrong. The page says which key; see Reverse proxy and HTTPS.
The browser reports a CORS error: The address the users type is not in APP_CORS_ALLOWED_ORIGINS.
Nobody receives e-mail: Search the log for [mail:log] and for Mail transport not configured; see Optional services.
A new organisation cannot sign in: Its owner has not opened the verification link yet. The link is valid for 24 hours and can be sent again from the registration page.
The registration form proposes no country: The location database is not loaded. It is optional; see Optional services.
I need to send information to Kubrik support: Send the answer of /actuator/info, the last lines of the log of backend and the time of the problem. Never send .env or the value of a key.

La aplicación de administración muestra una página de error en vez de la pantalla de ingreso: Su archivo opcional de ajustes está mal. La página dice qué clave; mirá Proxy inverso y HTTPS.
El navegador informa un error de CORS: La dirección que escriben los usuarios no está en APP_CORS_ALLOWED_ORIGINS.
Nadie recibe correo: Buscá en el registro [mail:log] y Mail transport not configured; mirá Servicios opcionales.
Una organización nueva no puede ingresar: Su dueño todavía no abrió el enlace de verificación. El enlace vale 24 horas y se puede mandar de nuevo desde la página de registro.
El formulario de registro no propone país: La base de ubicación no está cargada. Es opcional; mirá Servicios opcionales.
Necesito mandarle información al soporte de Kubrik: Mandá la respuesta de /actuator/info, las últimas líneas del registro de backend y la hora del problema. Nunca mandes .env ni el valor de una clave.