> ## Documentation Index
> Fetch the complete documentation index at: https://stellar-relay.xdr.ooo/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Check stream configuration, systemd state, and TCP NDJSON delivery.

Start with configuration completeness. Alert and case streams are configured independently, and a partially configured stream is treated as an error.

## A stream will not start

Verify that all required settings for the affected stream are present.

### Alert stream

```text theme={null}
--alert-interval
--alert-syslog-ip
--alert-syslog-port
```

### Case stream

```text theme={null}
--case-interval
--case-syslog-ip
--case-syslog-port
```

If all options for a stream are omitted, that stream is disabled. If configuration for a stream is started but a required option is missing, that stream is an error.

## The service is not running

Check the service state:

```bash theme={null}
sudo systemctl status stellar-alert-case.service
```

If the unit file was recently edited:

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl restart stellar-alert-case.service
```

Follow logs while reproducing the problem:

```bash theme={null}
journalctl -u stellar-alert-case.service -f
```

For automatic recovery, keep:

```ini theme={null}
Restart=on-failure
RestartSec=10
```

## The receiver gets no records

Check the path from the relay host to the destination:

1. Confirm the destination IP and port for the affected stream.
2. Confirm the receiver is listening on that TCP port.
3. Confirm firewall and network policy allow the connection.
4. Confirm the corresponding alert or case stream is fully enabled.
5. Confirm the receiver expects newline-delimited JSON over TCP.

## The receiver cannot parse records

The expected framing is:

```text theme={null}
JSON object + newline
JSON object + newline
...
```

Do not configure a parser that expects one large JSON document or traditional RFC syslog framing. Validate mappings with representative events from the deployed relay.

## Case fetching needs investigation

The recommended case configuration includes:

```bash theme={null}
--case-fetch-timeout 90 \
--case-include-summary \
--no-case-format-summary
```

Check these settings together with Stellar Cyber API reachability when case forwarding is delayed or incomplete.

## Debug mode

Use `--debug` only while troubleshooting.

<Warning>
  Disable debug mode after troubleshooting unless you intentionally need the additional logging in production.
</Warning>

## Quick checks

<CardGroup cols={2}>
  <Card title="Service state" icon="server">
    Confirm the systemd unit is active and inspect the journal for runtime errors.
  </Card>

  <Card title="Stream completeness" icon="list-check">
    Make sure every enabled stream has interval, destination IP, and destination port.
  </Card>

  <Card title="TCP reachability" icon="network-wired">
    Verify the relay host can reach each configured destination listener.
  </Card>

  <Card title="NDJSON parsing" icon="code">
    Confirm the receiver treats each newline-delimited JSON object as one event.
  </Card>
</CardGroup>