Troubleshooting

Where to look

Source	Command or place
Container state	docker compose ps
Service logs	docker compose logs --tail 100 api (or worker, gateway, web, openbao)
Failed jobs and their error	Actividad (Activity), filter Fallidas (Failed)
Who did what	Ajustes → Auditoría (Settings → Audit)
API health	curl -s http://127.0.0.1:8080/api/health

Installation

init.sh: Falta .env

Run cp .env.example .env and edit it before init.sh.

docker compose up fails with … es obligatoria

Compose refuses to start when a required variable is empty:

• POSTGRES_PASSWORD, ADMIN_EMAIL, ADMIN_PASSWORD or INFRAWARD_REGISTRY: set them in .env.
• OPENBAO_ROLE_ID, VAULT_OPENBAO_ROLE_ID or TERMINAL_OPENBAO_ROLE_ID (la escribe init.sh): run ./init.sh. This also happens after an upgrade that added a new AppRole.

init.sh: OpenBao ya está inicializado pero falta secrets/openbao/init.json

OpenBao is configured and the file with its root token was removed, as recommended. If nothing needs to change, you do not have to run init.sh. If an upgrade requires it, copy init.json back from where you stored it, run init.sh and remove the file again.

Podman: unknown mount option "uid=70"

Some Podman versions do not accept the uid= and gid= options that compose.yml uses for its tmpfs mounts. Replace them with Podman’s U option, which assigns the tmpfs to the container user:

sed -i -E 's/:uid=[0-9]+,gid=[0-9]+,mode=/:U,mode=/' compose.yml

Keep the change in mind when you update compose.yml on upgrades.

The API restarts in a loop

Check docker compose logs api. The API validates its configuration on start and stops with Configuración de entorno inválida: … naming the variable. Common causes:

• PUBLIC_URL tiene que ser https en producción: set INFRAWARD_PUBLIC_URL to an https:// URL.
• A variable added in an override file with a value out of range. See Configuration variables for the allowed values.

OpenBao shows an error in settings

Ajustes → Secretos shows openbao with a problem when the API or worker cannot log in with their AppRole:

1. Check docker compose ps openbao is healthy. If it is sealed after a restart and you removed the static seal, unseal it.
2. Check the role IDs in .env and the files in secrets/openbao/. If in doubt, run ./init.sh --rotate-secret-id and docker compose restart api worker gateway.

Sign-in and sessions

Signing in returns to the login page

The browser dropped the session cookie, which is Secure. This happens when InfraWard is opened over plain HTTP on any host other than localhost. Serve it over HTTPS. See HTTPS and reverse proxy.

Safari does not keep the session on localhost

Safari rejects Secure cookies on http://localhost. Use Chrome or Firefox for local tests, or put InfraWard behind HTTPS.

Write actions fail with 403

The API rejects write requests whose Origin does not match INFRAWARD_PUBLIC_URL. Check that the URL in .env is exactly the one in the browser’s address bar (scheme, host and port), then run docker compose up -d.

OIDC sign-in says the email is not verified

The message … no marca tu email como verificado means the provider did not send email_verified: true, so InfraWard does not create the account. Verify the email in the provider. If your provider never sends that claim (Microsoft Entra ID), set OIDC_ALLOW_UNVERIFIED_SIGNUP: "true" in api. See How accounts are created and updated.

The audit log shows the proxy’s IP for every user

INFRAWARD_TRUSTED_PROXY is unset or does not match the reverse proxy. See Find the proxy’s address.

The first administrator was not created

ADMIN_EMAIL and ADMIN_PASSWORD are only read when the database has no users, and the password needs at least 12 characters. Check docker compose logs api for a warning. If a user already exists, changing these variables has no effect.

An administrator lost the authenticator and the recovery codes

Another administrator resets the second factor from Ajustes → Usuarios. There is no reset from the command line, which is why you should always keep at least two administrator accounts (or an emergency local account when you use OIDC).

Enrolment

curl: (6) Could not resolve host or (7) Failed to connect

The server cannot reach INFRAWARD_PUBLIC_URL. Check DNS and firewalls from the server, or use the Script embebido (VPN/NAT) tab, which needs no connection to InfraWard.

The page stays on Esperando clave (Waiting for key)

The script did not finish or could not report back. Read the script output on the server. Each line starts with [infraward]; the last one before an error explains it. The token is single-use: generate a new command to try again.

The script stops because the clock is behind

In certificate mode, certificates are valid from 30 seconds before their creation. A server clock more than 5 minutes behind would reject them. Enable NTP (timedatectl set-ntp true) and run the command again.

sshd -t fails and the script rolls back

The script validates sshd before reloading it. The usual cause is an sshd_config without Include /etc/ssh/sshd_config.d/*.conf or an earlier file that already sets TrustedUserCAKeys or AuthorizedPrincipalsFile for all users. Fix the configuration and run the command again, or enrol with a static key.

The script stops on ~/.ssh or authorized_keys

In static key mode the script writes authorized_keys as the inventory user and checks the paths first. It stops without changing anything when:

• ~/.ssh or authorized_keys is a symbolic link. The script does not follow it, because a link such as ~/.ssh -> /root/.ssh would make root write somewhere else. InfraWard never creates such links: check the server, someone may have signed in as inventory.
• ~/.ssh or authorized_keys belongs to another user, or authorized_keys is not a regular file or has more than one hard link.
• The account already existed and its home directory does not belong to it ('inventory' no puede crear …/.ssh). Give the user ownership of its home directory, or remove the account and let the script create it.

Fix the cause and run the command again, or generate a new one if the token has expired.

Conectando (Connecting) fails with a host key error

The host key presented to the worker does not match the fingerprints the script reported. Check that the address you entered reaches the right machine (not a load balancer or a different host behind NAT).

Collection and scans

Find out why a collection or scan failed

Open the asset’s Recolecciones tab, or the job in Actividad, and select the failed run. Its log shows the step and command that failed, with the end of its error output. See Run logs.

Collection fails with Failed to create temporary directory

Fixed in InfraWard 0.5.2: upgrade. On 0.5.0 and 0.5.1, Ansible cannot write its temporary directory in the worker, whose root filesystem is read-only. Add a writable tmpfs for it in an override file (and add the file to COMPOSE_FILE):

compose.override.yml

services:
  worker:
    tmpfs:
      - /tmp:uid=1000,gid=1000,mode=0700
      - /home/node/.ansible:uid=1000,gid=1000,mode=0700

Then run docker compose up -d worker and select Recolectar de nuevo on the affected servers.

Collection is partial

The asset page shows La última recolección fue parcial with the reason. For example, without ss or netstat on the server, ports are read from /proc/net without the owning process. Install iproute2 to get process names.

Packages are missing on a Proxmox CT

Install python3 in the CT. Collection inside CTs runs through pct exec from the node and needs Python.

Scans wait for a long time after installation

On the first start, the worker downloads about 3 GB of Trivy data. Scans wait for it. Follow it with docker compose logs -f worker | grep -i trivy.

Podman containers do not appear

• The server shows sudoers desactualizado: Podman needs sudoers version 8. Regenerate the enrolment command and run it again.
• Rootless containers: the user must be enabled in the Usuarios de Podman card, and collected again afterwards. A user in Sin socket (No socket) is enabled but has no active podman.socket: run Habilitar again, which also turns on linger so the socket survives the end of the user’s sessions.
• A user with no running containers, no socket and storage outside ~/.local/share/containers is not detected. Add them with --podman-users.

A server shows hundreds of kernel vulnerabilities

Upgrade to InfraWard 0.6.0 or later. Earlier versions counted the findings of installed kernels that are not running, which dnf keeps on RHEL-family servers.

An image is marked as not scanned

The reason is shown on the image: larger than TRIVY_MAX_IMAGE_SIZE (4 GiB) or longer than TRIVY_SCAN_TIMEOUT (15 minutes). Raise the limits on the worker or exclude the image from scanning.

Alerts

Enviar prueba fails on a webhook

The last error is shown on the channel. Usual causes:

• The URL resolves to a private address, or uses http:: the worker rejects it unless ALERTS_WEBHOOK_ALLOW_PRIVATE or ALERTS_WEBHOOK_ALLOW_HTTP is true on the worker.
• The receiver redirects: redirects are not followed. Use the final URL.
• The receiver takes longer than ALERTS_TIMEOUT_MS (10 seconds) to answer.

Email channels do not send

The worker has no SMTP server configured (SMTP_HOST), or the server does not offer TLS. See Configuration variables.

Web terminal

Abrir terminal is not available

The server needs certificate mode and administration access enabled, OpenBao must be running and you need permission on the asset. See Web terminal.

The terminal says No se pudo cargar la terminal

Fixed in InfraWard 0.6.0: production builds of earlier versions could not load the terminal component. Upgrade.

Confirming your identity with authentik fails the second time

Fixed in InfraWard 0.6.0. authentik ignores max_age=0, which earlier versions sent, and returned a stale sign-in time from the second confirmation in the same browser session. Upgrade.

The terminal closes right after opening

The reverse proxy is not forwarding WebSocket upgrades on /gateway/, or it closes idle connections too early. See HTTPS and reverse proxy.