> ## Documentation Index
> Fetch the complete documentation index at: https://syteca.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Symptoms, causes, and fixes for the most common Syteca issues. Start here before opening a support ticket.

This page is symptom-first. Skim the headings until you find the one that matches what you are seeing, then work through the checks in order.

If nothing here matches, collect the diagnostic bundle described at the bottom of the page and [contact support](https://support.syteca.com).

## Client connectivity

### A new client doesn't appear in the Management Tool

The client installed cleanly but never registered with the Application Server.

<Steps>
  <Step title="Confirm the service is running">
    On the endpoint, run `sc query SytecaClient`. State must be `RUNNING`. If it isn't, start it: `sc start SytecaClient`.
  </Step>

  <Step title="Test network reachability">
    From the endpoint:

    ```powershell theme={"system"}
    Test-NetConnection -ComputerName syteca.acme.local -Port 9447
    ```

    `TcpTestSucceeded` must be `True`. If not, you have a firewall or routing issue between the endpoint and the Application Server.
  </Step>

  <Step title="Check the agent key">
    A wrong agent key means the server silently drops the registration. Re-copy the key from **Clients → Add client** and re-run the installer with `REPAIR=1`.
  </Step>

  <Step title="Inspect the client log">
    Open `%ProgramData%\Syteca\Client\logs\client.log`. A registration rejection logs as `RegisterFailed: <reason>`.
  </Step>
</Steps>

### The client appears, then goes Offline within minutes

The client registers but the heartbeat fails. Almost always a network or TLS issue.

<AccordionGroup>
  <Accordion title="TLS certificate problem">
    The client requires a TLS certificate that chains to a trusted root on the endpoint.

    On the endpoint, run:

    ```powershell theme={"system"}
    Test-NetConnection syteca.acme.local -Port 9447 -InformationLevel Detailed
    ```

    Then inspect the certificate in **Certificates (Local Computer) → Trusted Root Certification Authorities**. The issuing CA must be present.
  </Accordion>

  <Accordion title="Outbound proxy stripping the connection">
    Some corporate proxies break long-lived TCP connections. Add the Application Server hostname to the proxy bypass list.
  </Accordion>

  <Accordion title="Time skew">
    More than 5 minutes of clock drift between client and server invalidates the registration token. Confirm the endpoint syncs to a known time source.
  </Accordion>
</AccordionGroup>

## Session recording

### Sessions are recorded but the Session Player shows a black screen

Almost always a video codec or GPU driver issue on the playback machine, not on the recording endpoint.

<Steps>
  <Step title="Try a different browser">
    The Session Player runs in the browser. Try the same session in Chromium and Firefox. If one works and the other doesn't, you have a browser codec issue.
  </Step>

  <Step title="Confirm the file exists">
    In **Sessions your session Storage**, check the file size. A black-screen session with `0 KB` was never written; see [the next entry](#sessions-arent-being-written-to-disk).
  </Step>

  <Step title="Check the recording parameters">
    If **Full-Motion Capture** is enabled but the endpoint's GPU is in software-rendering mode (RDP without GPU passthrough, for example), some frames may be black. Disable Full-Motion for affected endpoints.
  </Step>
</Steps>

### Sessions aren't being written to disk

The Application Server is accepting the session start event but the file isn't growing.

<Steps>
  <Step title="Check storage capacity">
    The session-store volume must have at least 10% free space. The server stops writing at 90% usage to avoid corrupting in-flight sessions.
  </Step>

  <Step title="Confirm the storage path is writable">
    The Syteca Application Server service account must have **Modify** rights on the session-store path.
  </Step>

  <Step title="Review the server log">
    Open `C:\ProgramData\Syteca\Server\logs\server.log` and search for `SessionWriter`. Errors there name the cause.
  </Step>
</Steps>

## Alerts and notifications

### Alerts trigger in the UI but no email is sent

<AccordionGroup>
  <Accordion title="SMTP not configured">
    Check **Settings → Notifications → SMTP**. A blank server here means no email backend is configured.
  </Accordion>

  <Accordion title="SMTP credentials rejected">
    The server log records SMTP failures as `SmtpFailed: 5.7.1 ...`. If you see this, regenerate the SMTP password or app-password and update Syteca.
  </Accordion>

  <Accordion title="Alert rule has no recipients">
    A rule with an empty **Notify** list triggers in the UI but sends nothing. Edit the rule and assign at least one recipient or distribution list.
  </Accordion>
</AccordionGroup>

## PAM and secrets

### A user can't retrieve a secret they should have access to

Permissions on secrets are layered (user → role → project). Check each layer.

<Steps>
  <Step title="Confirm the user is enabled and not locked">
    Locked or expired users see secrets in the UI but cannot retrieve them. **Users user Status** must be **Active**.
  </Step>

  <Step title="Inspect direct secret permissions">
    Open the secret. The **Permissions** tab lists every principal with explicit access.
  </Step>

  <Step title="Inspect role-inherited permissions">
    A user inherits secret permissions from every role they belong to. Use **Users user Effective permissions** to see the merged set.
  </Step>

  <Step title="Check project membership">
    Secrets scoped to a project require project membership. **Projects project Members** must include the user or one of their roles.
  </Step>
</Steps>

## Database

### The Application Server logs `database_unavailable` errors

<Steps>
  <Step title="Confirm the database is up">
    Connect with `psql` or SQL Management Studio from the Application Server host using the same credentials Syteca uses.
  </Step>

  <Step title="Check connection limits">
    PostgreSQL's `max_connections` must be at least 200 for a medium deployment. The Application Server reports `connection_limit_reached` when it can't get a connection.
  </Step>

  <Step title="Validate the NOSUPERUSER setup on 7.23+">
    On Syteca 7.23 and later, the database user must be configured as `NOSUPERUSER` with explicit grants. See [PostgreSQL NOSUPERUSER setup](/docs/administration/database/creating-databases-manually#grant-extra-privileges-syteca-7-23-and-later-only).
  </Step>
</Steps>

## Collecting a diagnostic bundle

If you need to open a support ticket, attach a diagnostic bundle. Run on the Application Server:

```powershell theme={"system"}
Invoke-SytecaDiagnostics -OutputPath "$env:TEMP\syteca-diag.zip" -IncludeLogs -IncludeConfig
```

The bundle includes server logs, configuration (with secrets redacted), platform info, and recent audit events. Attach the zip to your support ticket — do not paste log contents inline.

<Note>
  The bundle never contains recorded session data, secrets, or user passwords.
</Note>