Troubleshooting

The failures that actually happen, each with the command that diagnoses it.

Access denied because search permissions are missing

AH00035: access denied because search permissions are missing on a component
of the path /opt/loghound/public/index.php

The prefix is not traversable by the web server user. Fix it by mode:

sudo chmod 0751 /opt/loghound
sudo -u www-data test -x /opt/loghound && echo "traverse ok"

Do not add the web server user to the group. That needs an Apache restart rather than a reload, which drops in-flight requests on every other site on the box. The permission model explains why.

It answers 503 and refuses

That is authentication failing closed: no sign-in mode is configured. It is the state a fresh install is in before setup finishes, and it is deliberate — signing in.

Unable to get local issuer certificate, in every browser

You are serving a certificate that does not chain to a trusted root — very often a Let’s Encrypt staging certificate, which has valid dates and the right hostname and looks entirely fine until a browser checks it.

openssl x509 -in /path/to/fullchain.pem -noout -issuer -dates
openssl verify -untrusted /path/to/fullchain.pem /path/to/fullchain.pem

Re-issue without the staging flag, then re-run the installer with the existing-certificate mode. The installer refuses to deploy one that fails this check, which is why it is worth letting it choose.

loghound-tail --status --human

Look at the lag, the parse errors and the Solr errors. Then replay the whole file, parsing it and writing nothing:

sudo -u loghound php /opt/loghound/bin/loghound-tail --once --from-start --dry-run --verbose

If that reports documents, the pipeline works and the problem is either Solr connectivity or simply the fact that a newly watched file is read from its end.

No documents after sixty seconds on a quiet site

Probably correct behaviour: there were no requests, and a newly watched file starts at the end. Generate some traffic, or ingest the existing file once from the start.

The status says stale

The status file has not been updated for more than ten seconds, so the daemon has probably died:

journalctl -u loghound-tail -n 50 --no-pager

sudo tail /opt/loghound/var/badlines.log

Every unparseable line is counted and a capped sample is written there with its source file and byte offset — never silently dropped. Usually it means the configured format no longer matches the file, which happens when somebody changes the log format without re-running the wizard:

sudo -u loghound php /opt/loghound/bin/loghound-setup

ls -ld /var/log/apache2 /var/log/nginx
sudo -u loghound test -r /var/log/apache2/access.log && echo ok || echo denied

The directory usually needs to be group adm and group-readable. Note that group membership added a moment ago applies only to new processes — which is why the installer tests with a fresh one rather than trusting the group listing. If you cannot change the group, an access-control entry works:

sudo setfacl -m u:loghound:rx /var/log/apache2
sudo setfacl -m u:loghound:r  /var/log/apache2/example_com_access.log

• A card shows an error and the rest of the page is fine. That is the design: every card fails alone, and the message names the fix rather than being a stack trace. Retry re-runs that one card.
• A connection banner appears at the top. It is revealed once, with the first real diagnosis and a link to the connection check under Settings. Nothing pinged anything to decide that.
• The cards never leave their loading state. Scripting is off. The page, its navigation, the range picker, the session search and every settings form still work.
• The installer keeps reappearing on a working install. That was a real bug and it is fixed: the gate is now structural and no longer asks the configuration validator, which reports an error for a log directory the panel process cannot resolve under its own path restriction. If you see it, check that the configuration file exists, carries a username and a password hash, and names both indexes — those three conditions are the whole of it.
• Session totals look slightly high. Daily rollup documents are currently counted as sessions, by up to one per day in the selected range. It is a known bug in the panel’s query construction, recorded as such rather than presented as a trade-off.

1. Check the tag is actually on the page, and that the URL in it is the Loghound host.
2. Check the content security policy on the measured site. Missing the connection directive is the commonest cause and it fails completely silently — two directives.
3. Check compression, which is not a failure but is worth knowing: curl -sI -H 'Accept-Encoding: gzip' https://loghound.example.com/b.js | grep -i content-encoding
4. If the site is on another machine, its hostname has to be on the allowlist before its beacons may create a session — standalone mode.
5. Remember a large share of real humans block it. Ad blockers and script blockers stop it entirely, and that is expected rather than broken — false positives.