Skip to content

Installation diagnostics

Locate the symptom, then return to the relevant procedure after correcting the cause.

Symptom Check Procedure
PostgreSQL unreachable Running service, address and port, pg_hba.conf rule; if PostgreSQL is encrypted, hostssl rule, CA and certificate name PostgreSQL, PostgreSQL SSL
Missing vector or unaccent Extension installed for PostgreSQL 18, then enabled in the correct database Databases
init failure Same YAML and environment as the future service, database connection, available storage Platform
Inactive Linux service Paths, application account permissions, message in journalctl -u <unit> Operations
Worker stopped at startup API started and database schema installed: schema-wait waits up to 300 seconds Operations
Stopped Windows service Status through Get-Service, service environment and logs in C:\app\logs\<component> Operations
TLS error or unknown certificate SAN matching the URL, complete chain, trusted client CA, system time Install your certificates
Frontend service accessible only locally Listener address, VM DNS, client network filtering and port 9000 Install the Frontend
Frontend service running but sign-in fails Internal link state, then exact CORS origin Internal link, Operations
External API clients get no response Public listener address smartagt.http.public.host, Backend certificate, port 8000 filtering Install the Backend
502 behind the proxy Upstream name resolution, port, verified upstream certificate and reachable service Reverse proxy
Response displayed all at once Proxy buffering and read timeout, then provider streaming Reverse proxy
License rejected Received file, validity period, clock and validation message Activation
Missing model or denied access Provider type, key, exact model reference and activated capability Getting started
Document without results Active rag-ingestor and rag-embed, configured default embedding, reachable storage and provider Getting started
Gateway returns address_not_allowed Observed client address, trusted proxy and Gateway network list Enable AI Gateway

Service names and log paths are listed in Configuration. Correct certificate errors in the trust chain or name used. Keep TLS verification; do not replace the application account with an administrator to bypass a file permission error.

The Frontend service stays in service when its link to the API is unavailable: it answers 503 with the internal_link_unavailable reason and the cause, then retries by itself, with an interval growing from one second to one minute. The API does not stop either, and its Public listener remains served. The cause can be read without authentication at the Frontend service /api/v1/platform/internal-link route. On the Backend, run.bin pki status --config followed by the Backend YAML displays the internal authorities, the internal URL, the state of ports 8010 and 8011, replicas with their cause, and fingerprints.

Cause Meaning Action
backend_unreachable The Internal listener does not answer at the internal URL Start the API; check port 8010, the firewall between servers and the load balancer. The link recovers by itself.
enrollment_required Frontend service not enrolled yet, or identity refused On an API server: check in pki status that the local enrollment endpoint answers. Without an API on the server: configure the deployment secret on both sides.
jwt_key_missing Backend session public key missing Run the Frontend service init again once the API is started, then restart it.
backend_key_changed The Backend presents another session key or another installation Backend intentionally reset or restored: run the Frontend service init again, with --adopt-backend-key when the key is read from the local enrollment endpoint, then restart it. Otherwise, check the internal URL target.
component_retired Frontend service withdrawn by pki revoke --component bff Readmit: run.bin pki revoke --component bff --reopen-local on the API server, then restart the Frontend service within 10 minutes; or a new secret produced by pki generate-join-secret, on both sides.
backend_outdated Backend older than the Frontend service Update the Backend with the same delivery.
intermediary_terminates_tls An intermediary terminates TLS between the Frontend service and the API Replace it with a direct connection or a load balancer in plain TCP passthrough (layer 4).
internal_name_mismatch The presented certificate does not carry the internal URL name Check that the internal URL leads to the Internal listener, without an intermediary that terminates TLS.
internal_url_mismatch An API node YAML carries an internal URL other than the installation's Copy the URL shown by pki status into this node's smartagt.http.internal.url, then restart it.
port_occupied Port 8010 or 8011 is used by another program Free the port; the API retries by itself.
database_unavailable Backend or Frontend service database unavailable Restore PostgreSQL; loaded certificates remain served and the link recovers by itself.

To report a blocker, provide the step, package version, exact message and a timestamped log excerpt without secrets. Contact SmartAGT.