Troubleshooting

This page collects the issues operators hit most often, grouped by where they show up. Most are intentional safety checks: VaultTerm prefers to refuse to start rather than run insecurely. For conceptual background, see Security model and Configuration overview.

Server refuses to boot

Symptom	Cause	Fix
Server exits at startup under NODE_ENV=production complaining about the JWT secret	Weak, missing, or default JWT_SECRET	Set JWT_SECRET to a strong value of at least 32 bytes. The server refuses to boot in production with a weak or default secret.
On-prem server exits at startup citing licensing	No valid license present	Provide a valid signed offline license. On-prem will not boot without one — see Licensing and activation.

Generate a strong secret, for example:

openssl rand -base64 48

Then set it in the environment:

NODE_ENV=production
JWT_SECRET=<at least 32 bytes of high-entropy value>

TLS, WebAuthn, and cookies

WebAuthn and secure cookies require HTTPS. The only origin exempt from this is localhost.

• In any real deployment, put a TLS reverse proxy in front of VaultTerm and terminate HTTPS there.
• Without HTTPS off localhost, WebAuthn registration and step-up will fail and secure cookies will not be set, so sessions and sensitive reveals break.

A minimal reverse-proxy sketch:

server {
    listen 443 ssl;
    server_name vaultterm.example.com;

    ssl_certificate     /etc/ssl/certs/vaultterm.example.com.crt;
    ssl_certificate_key /etc/ssl/private/vaultterm.example.com.key;

    location / {
        proxy_pass http://127.0.0.1:4000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }
}

Admin / platform plane is unreachable

The admin / platform plane binds to loopback by default. This is intentional — it must not be exposed to the network.

• Reach it over an SSH tunnel to the host, never by binding it to a public interface.
• For example, forward the local plane port through SSH and open it on your own machine:

ssh -L 9000:127.0.0.1:<plane-port> [email protected]

See admin console.

Outbound requests to private addresses fail

Under production, server-side fetches to RFC1918 / private targets (for example 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) are blocked by default to prevent SSRF-style egress.

• If a feature legitimately needs to reach a private target (for example an internal service or a self-hosted model endpoint), set EGRESS_ALLOW_PRIVATE=1.
• Leave it off unless you specifically need it. See AI and egress configuration.

EGRESS_ALLOW_PRIVATE=1

Health, readiness, and metrics

Endpoint	Purpose	Notes
/health	Liveness probe	Is the process up
/readyz	Readiness probe	Is the instance ready to serve traffic
/metrics	Prometheus metrics	Requires the METRICS_TOKEN bearer token to scrape

Wire /health and /readyz into your orchestrator’s liveness and readiness checks. To scrape metrics, send the configured bearer:

curl -H "Authorization: Bearer $METRICS_TOKEN" https://vaultterm.example.com/metrics

See Observability.

Still stuck

If your question is conceptual rather than a specific failure, see the FAQ. For self-hosting specifics, see Self-hosting FAQ.