Organised by the error text you will actually see, so this page is findable by pasting the message into a search box. Each entry gives the cause, the fix, and where relevant a command that confirms which of several causes you have.
1Startup and connectivity
hdbcli.dbapi.Error: (-10709, "Connection failed (RTE:[89006] System call 'connect' failed, rc=111:Connection refused)")
Cause
Nothing is listening on HANA_HOST:HANA_PORT from inside the container. Almost always one of: the wrong port for your instance type, localhost used where the container's own loopback is meant, or a firewall between the Docker host and HANA.
Fix
Use 3<instance>15 for a tenant database and 3<instance>13 for a single-container system. From the host, host.docker.internal reaches your machine; localhost never does from inside a container.
Confirmdocker compose exec backend python -c "import socket;socket.create_connection(('HOST',PORT),5)" — a clean exit means the path is open and the problem is credentials, not networking.
authentication failed: invalid username or password
Cause
Credentials are right but the user is locked, expired, or forced to change password at next logon — HANA reports all of these the same way.
Fix
Check SYS.USERS for USER_DEACTIVATED and PASSWORD_CHANGE_NEEDED. A technical user should be created with NO FORCE_FIRST_PASSWORD_CHANGE and a password policy that does not expire, or answers stop at an interval nobody remembers configuring.
dial tcp: lookup loki on 127.0.0.11:53: no such host
Cause127.0.0.11 is Docker's embedded DNS, which only resolves names of containers that are running. This says the loki container is not up — it is not a networking fault, and not a Grafana fault.
Fixdocker compose ps loki. If it is exited or restarting, docker compose logs loki --tail=50 will show the reason on the first line — a configuration parse error is the usual one, and Loki exits on unknown keys rather than ignoring them.
Confirm
The same shape applies to any service name in a compose stack: lookup <name> ... no such host means that service exited.
2Permissions and schema
insufficient privilege: Not authorized
Cause
The HANA user can connect but cannot read the object the query needs. Common after a new company schema is added and the grant is not extended to it.
FixGRANT SELECT ON SCHEMA <SCHEMA> TO <USER>;. Grant on the schema rather than table by table, or every new user-defined table becomes a support ticket.
PermissionError: [Errno 13] Permission denied: '/app/schema/snapshot.json'
CauseSCHEMA_SNAPSHOT_DIR points somewhere the container user cannot write. Typically a bind mount owned by root on the host.
Fix
Point it at a named volume, or chown the host directory to the container's UID. A named volume is the less surprising of the two.
SCHEMA_REFRESH_HOURS to come around.3Answers that are wrong rather than failing
These are worse than errors, because nothing looks broken. Each has a characteristic shape.
3.1The number is right but the period is wrong
Ask for "last quarter" and get October to December. The fiscal calendar is not configured, so calendar quarters are being used. Indian fiscal years run April to March and Q1 is April to June; set the fiscal calendar for the company and re-ask. Every answer that mentions a period is suspect until you have.
3.2Sales look too high by roughly the tax
DocTotal includes GST. A revenue figure should normally sum LineTotal from the lines, or DocTotal - VatSum. If a number is about 18% larger than the finance team expects, this is nearly always why.
3.3A customer appears twice with different spellings
Two business-partner master records. Run the duplicate check in the master data recipes — matching on GSTIN catches the unambiguous cases. Merging them is a master-data job, not something a reporting tool should paper over.
3.4Totals disagree with a Crystal Report by a small amount
Usually cancelled documents, or credit notes counted on one side and not the other. Open the working under the answer, compare the documents it says it used against the report's selection formula, and one of the two will be leaving out cancelled documents or the returns. The working exists precisely so this argument can be settled in a meeting rather than after it.
4Performance
504 Gateway Time-out (nginx)
Cause
The answer took longer than the proxy's read timeout. Common on the first question after startup, when the schema snapshot is being built.
Fix
Raise proxy_read_timeout to at least 120s. If it persists beyond the first question, the query itself is slow — read the timing in the working to see whether the time is in HANA or in retrieval.
too many outstanding requests
Cause
Loki's per-tenant query queue is full. A dashboard refreshing many panels against a small single-binary Loki will do this.
Fix
Raise frontend.max_outstanding_per_tenant and lengthen the dashboard's refresh interval. Note the setting lives under frontend — it does not exist under limits_config, and putting it there stops Loki starting at all.
MAX_RETRIEVAL_STEPS or turn off EXTENDED_THINKING and measure again.5Getting help
When reporting a problem, the useful three things are: the question as typed, the time it was asked, and docker compose logs backend --tail=200. With those, most issues are diagnosable without access to your data.