troubleshooting

permission denied

Error: Permission denied: /var/log/syslog

Some logs (/var/log/secure, /var/log/messages) are root-only by default. logcrux runs with the caller's privileges and has no special powers of its own. Pick whichever fits your setup:

# Run as root for ad-hoc analysis
sudo logcrux /var/log/secure

# Least-privilege for the journal: join systemd-journal, pipe journalctl
sudo usermod -aG systemd-journal "$USER"     # then re-login
journalctl -o short-iso | logcrux

# Grant a read-only user access via ACLs
sudo setfacl -m u:loguser:r /var/log/secure

wrong parser detected

Parsed with: nginx-access (but it's actually apache)

Override it directly, and check the formats index to confirm the detection markers for your format:

logcrux /var/log/access.log --format apache-access

many lines skipped

Parsed: 100 events, Skipped: 5000 events

The detected parser isn't matching most lines, usually because the file is a mix of formats or an unusual variant. Check the raw content, then either force a format or let the built-in safety net take over (it already does this automatically if the detected parser covers under 60% of the file):

head -20 /var/log/mylog.log
logcrux /var/log/mylog.log --format syslog

no anomalies detected but you expected some

Output: CLEAN, no anomalies detected

Try, in order:

# Lower the AI confidence threshold
logcrux /var/log/syslog --threshold 0.2

# See what the analysis engines are actually finding
logcrux /var/log/syslog --verbose

# Skip baseline comparison if the state DB is new/thin
logcrux /var/log/syslog --no-baseline

You can also loosen the statistical thresholds in config:

analysis:
  burst_multiplier: 2.0   # more sensitive
  spike_factor: 2.0

too many false positives

Output: CRITICAL on what looks like normal operation

# Raise the confidence threshold
logcrux /var/log/syslog --threshold 0.7

Or tighten the statistical thresholds:

analysis:
  burst_multiplier: 5.0   # only alert on 5x baseline
  spike_factor: 5.0

If you're comparing against a baseline, let it run for 24+ hours first. A thin or fresh baseline treats everything as anomalous relative to almost nothing.

all incidents classified as unknown

Category: UNKNOWN (0.15 confidence)

Confidence is below the classification threshold. Lower it, or confirm the local models are actually present (a shallow or partial clone can leave them missing, in which case logcrux says so plainly and still runs statistical analysis):

logcrux /var/log/syslog --threshold 0.1
ls -lh logcrux/inference/models/*/model.onnx   # dev checkout only

baseline not updating

Baseline unchanged across multiple analyses

Usually --no-baseline was passed, or the state DB isn't writable:

ls -la ~/.local/share/logcrux/
chmod 700 ~/.local/share/logcrux/
chmod 600 ~/.local/share/logcrux/state.db

# Or just reset it
rm ~/.local/share/logcrux/state.db

database locked

Error: Database is locked

Another logcrux process is writing at the same time.

pgrep logcrux
killall logcrux

# Or sidestep the state DB entirely
logcrux /var/log/syslog --no-baseline

analysis is slow on a large file

logcrux /var/log/syslog --last 1h
tail -n 100000 /var/log/syslog | logcrux

Both narrow the input before analysis instead of loading and processing the whole file.

no output at all

$ logcrux /var/log/syslog
(nothing printed)

# Force unbuffered output and surface any hidden error
stdbuf -oL logcrux /var/log/syslog
logcrux /var/log/syslog 2>&1 | cat

unicode / decode errors

Error: UnicodeDecodeError: 'utf-8' codec can't decode byte...

The log has non-UTF-8 bytes (common on older Windows-exported logs). Convert it first:

iconv -f ISO-8859-1 -t UTF-8 /var/log/syslog > /tmp/syslog_utf8
logcrux /tmp/syslog_utf8

config file not found or not applied

logcrux checks, in order:

--config PATH
~/.config/logcrux/logcrux.yaml
/etc/logcrux/logcrux.yaml
built-in defaults

# Confirm it's being read
logcrux /var/log/syslog --verbose 2>&1 | grep -i config

# Or force it explicitly
logcrux /var/log/syslog --config /path/to/custom.yaml

See config for the full field reference; every field is validated, so a typo'd key fails loudly at startup rather than silently keeping the default.

filing a bug report

Gather the basics and open an issue:

logcrux /path/to/log --verbose > /tmp/logcrux.log 2>&1
logcrux --version
python --version
uname -a

Include a small log sample (first 50 lines), the verbose output, and what you expected versus what happened. Open an issue on GitHub.