Install troubleshooting

Operations · Cluster administrators · Applies to 5.0.x

Use this page when installation, first admin setup or first public API checks do not behave as expected.

Checklist

1. Confirm the supported package repository at repo.eldric.ai is reachable from the host.
2. Confirm the installed package version matches the intended 5.0.x line.
3. Confirm DNS and TLS for the public entry point before testing browser or API clients.
4. Confirm the first administrator flow has completed once and is not being repeated by another user.
5. Confirm the license file or evaluation mode matches the intended tier.
6. Confirm the public health endpoint responds before testing higher-level workflows.

Common symptoms

The first four checks, with the commands

Each of these answers one question and needs nothing installed but curl. Run them in order — the first that fails is where the problem is.

1. Is the repository reachable and a valid dnf repo?
   curl -fsS https://repo.eldric.ai/5.0/repodata/repomd.xml > /dev/null && echo ok
   Anything other than ok is a network or proxy problem, not a package problem.
2. Is this OS supported? The installer reads /etc/os-release and requires Fedora 42+, or RHEL / CentOS 9+; RHEL-family derivatives such as Rocky and Alma are accepted when they declare a RHEL family and major 9 or newer. On an unsupported release the installer exits 2 and says which version it found.
   . /etc/os-release; echo "$ID $VERSION_ID"
3. Is the daemon actually up?
   curl -fsS http://localhost:8880/health
   It reports the running version. If this answers, the install worked and the problem is in front of the daemon — TLS, hostname or routing.
4. Is a 401 about the key or the session?
   curl -fsS -H "X-API-Key: <key>" http://localhost:8880/api/v1/auth/whoami
   A successful reply lists the scopes that key actually carries; comparing them with the scope the endpoint needs turns a 401 into a specific answer.

Every command above is read-only and safe to run on a production node.

Symptom	Likely next step
Package install fails	Check repository reachability, OS support and package signature trust.
Browser cannot open chat	Check hostname, TLS and public route.
API returns 401	Check API key, session state and tenant scope.
RAG upload succeeds but no citations appear	Check indexing status and selected knowledge base.
macOS package warning	Use the signed package workflow documented by Eldric support.

For unresolved install issues, contact office@eldric.ai with version, operating system, deployment shape and the redacted error message.