The gateway refuses to start

The gateway refuses to start when a required variable is missing or when a configuration is inconsistent; it does not start with a fallback. The startup message names what is missing. Start by reading it.

DATABASE_URL is missing

The gateway reads its configuration (endpoints, models, inference engines) from its database. Without a database address, it has nothing to serve.

export DATABASE_URL="postgresql://<utilisateur>:<mot-de-passe>@<hôte>:<port>/<base>"

Do not add any encryption parameter to this address: that is a cause of refusal in its own right, covered in the next section.

An encryption parameter in the database address

This cause often comes from a setting added to get the connection working. Five address parameters cause the gateway to refuse to start:

sslmode, ssl, sslrootcert, sslcert, sslkey

The PostgreSQL library gives priority to what the address carries over what the code has set. A single one of these parameters replaces the entire encryption configuration, including the certificate authority you declared. The gateway stops and names the parameter.

The refusal applies only to remote databases. A database on the machine itself (localhost, 127.0.0.1, a file socket) is joined without TLS, and nothing is refused there.

What to do

Remove the parameter from the address. Then, if the database presents a certificate signed by an internal authority, declare that authority:

export DATABASE_URL="postgresql://<utilisateur>:<mot-de-passe>@<hôte>:<port>/<base>"
export DATABASE_CA_CERT_PATH="/etc/ssl/certs/<autorité-interne>.pem"

Where the platform running the gateway passes only variables and mounts no files, DATABASE_CA_CERT carries the certificate content instead of its path. Set one or the other: both at once cause the gateway to refuse to start.

No setting disables certificate verification. A database whose certificate cannot be validated is handled by adding its authority.

The address host: a DNS name

Write the DATABASE_URL host as a DNS name, not an IP address. For an IP address, the PostgreSQL client sends no server name, and verification falls back to “localhost”, which no database certificate carries. The connection then fails with a message about the name.

ADMIN_API_KEY is missing

This is the API key of the administrator account, which the gateway creates on its first start. In the hosted profile, the gateway refuses to start without it. In the on-premise profile, this variable is not read: identities come from the company directory.

export ADMIN_API_KEY="<la clé d'administration de cette installation>"

It starts, but every request fails

The symptom is different: the gateway is healthy, it is the relay to the inference engine that fails. The gateway has no destination outside your perimeter (security white paper V3, section 3.3): the causes are to be found on the internal path between it and the engine. Three frequent causes.

The engine requires a key, and its variable is not defined. The name of the expected variable is not fixed in the code: it is recorded in the database, in the api_key_env column of the declared engine. An omission only shows up on the first request, in the form of a 500 response that names the variable. Note the expected name in the administration console, then define the variable.

The engine’s certificate is signed by an internal authority the gateway does not know. NODE_EXTRA_CA_CERTS designates that authority; this store is added to the system roots, on all paths to the engine, including when UPSTREAM_TLS_CA_FILE or a client certificate is configured. No setting disables verification of the engine’s certificate.

Network filtering does not let the gateway host reach the engine, or an internal proxy is wrongly declared for this path. The gateway follows the proxy its environment declares: HTTPS_PROXY for an https target, HTTP_PROXY for an http target and as a fallback for https targets, NO_PROXY for hosts joined directly, which allows the inference engine not to go through the proxy. If none of these variables is set, the gateway reaches the engine directly. The startup log announces the proxy selected for each protocol, the excluded hosts and the trust store in use, or else that no proxy is configured. Start by reading this line.

Two configuration errors stop the gateway at startup, with the name of the variable at fault: a proxy value that is not a full URL, and a NODE_EXTRA_CA_CERTS that points to an unreadable file. The detail of each variable: Gateway environment variables.

Checking that the gateway responds

There is no dedicated health route. The check consists of calling a nonexistent route and verifying that it responds 401, which shows that the service is listening and that authentication applies:

curl -s -o /dev/null -w '%{http_code}\n' https://<hôte>:<port>/healthz/v1/models

A 401 response is the expected result. No response means the service is not listening.