Skip to content

Troubleshooting

Common Issues

"No connection could be made because the target machine actively refused it"

Cause: The syslog server is not listening on the specified host and port.

Fix:

  1. Verify the syslog server is running and accepting connections
  2. Check the Host and Port settings
  3. Confirm any firewalls allow traffic on the configured port
  4. Test connectivity: Test-NetConnection -ComputerName <host> -Port <port>

"STOPPED - 10 consecutive failures"

Cause: The forwarder hit the maximum consecutive failure threshold and stopped automatically.

Fix:

  1. Check the log output for specific error messages
  2. Verify network connectivity to the syslog server
  3. Fix the underlying issue, then click Start to resume

TLS Handshake Failures

Symptoms: TLS authentication failed in the log output, or AuthenticationException.

Common causes:

Error Likely Cause Fix
RemoteCertificateNameMismatch Hostname doesn't match cert Use the FQDN that matches the certificate
RemoteCertificateChainErrors Self-signed or untrusted CA Install CA cert, or uncheck Validate Cert
RemoteCertificateNotAvailable Server didn't present a cert Check server TLS configuration
Handshake timeout Server doesn't support TLS 1.2/1.3 Upgrade the server, or use plaintext

No Records Read

Symptoms: Every poll shows 0 records read.

Possible causes:

  1. No new log activity -- Archestra hasn't written new records since the last cached position
  2. Wrong log directory -- The reader can't find .aaLog files
  3. Cache file ahead of data -- The cached message number is beyond the latest record

Fix:

  • Check that .aaLog files exist in the expected directory (see Log Directory)
  • Try checking Send Existing Logs and clicking Start to bypass the cache
  • Delete the cache file (see below) to force a full re-read

Settings Not Persisting

Cause: The settings directory is not writable, or the JSON file is corrupted.

Fix:

  1. Check that %LOCALAPPDATA%\aaLogForwarder\ exists and is writable
  2. Delete settings.json to reset to defaults
  3. Check the log4net log for "Failed to save settings" warnings

Log Files

Forwarder Log

The forwarder writes its own diagnostic log to:

aaLogForwarder.log

This file is in the working directory (typically the same folder as the executable). It records:

  • Startup and shutdown events
  • Settings load/save operations
  • Network errors and retry attempts
  • TLS certificate validation results

Debug Log

For detailed diagnostics, enable the debug appender in log.config:

<root>
  <level value="DEBUG"/>
  <appender-ref ref="DebugFileAppender"/>
  <appender-ref ref="FileAppender"/>
</root>

The debug log (aaLogForwarder-debug.log) includes:

  • Every GetUnreadRecords call with parameters
  • Cache file reads and writes
  • File open/close operations
  • Header parsing details
  • Individual record reads

Warning

Debug logging is extremely verbose and can fill disk quickly. Only enable it for active troubleshooting, then revert the configuration.

Cache File

Location

The cache file is in the same directory as the .aaLog files:

C:\ProgramData\ArchestrA\LogFiles\aaLogGUITester-aaLogReaderCache

Resetting the Cache

If the cache file becomes stale or points to a position that no longer exists:

  1. Stop the forwarder
  2. Delete the cache file
  3. Start the forwarder

Alternatively, check Send Existing Logs before starting -- this ignores the cache on the first poll.

Cache File Contents

The cache file is a JSON-serialized LogRecord. You can inspect it to see the last-read message number:

Get-Content "C:\ProgramData\ArchestrA\LogFiles\aaLogGUITester-aaLogReaderCache" | ConvertFrom-Json | Select-Object MessageNumber

Backoff Behavior

When a network error occurs, the forwarder waits before retrying. The wait time doubles on each consecutive failure:

Failure # Wait (1s interval)
1 1 s
2 2 s
3 4 s
4 8 s
5 16 s
6--10 30 s (cap)

The backoff resets immediately after any successful poll. After 10 consecutive failures, forwarding stops.

The log output shows backoff timing:

*** Network error: No connection could be made because the target machine actively refused it ***
Backing off for 2000ms (failure #2)

Verification Checklist

Use this checklist when setting up a new forwarding destination:

  • [ ] .aaLog files exist in the expected log directory
  • [ ] Syslog server is reachable: Test-NetConnection -ComputerName <host> -Port <port>
  • [ ] Firewall rules allow outbound traffic on the configured port
  • [ ] If using TLS: server supports TLS 1.2 or 1.3
  • [ ] If using TLS with validation: certificate is trusted or CA is installed
  • [ ] Forwarder shows records read counts greater than zero
  • [ ] Syslog server is receiving and parsing messages correctly
  • [ ] Check syslog format compatibility (RFC 5424 vs. RFC 3164 vs. KVP)