Application troubleshooting

This guide covers issues you may encounter after a successful installation. Each section covers one component.

Applies to

This guide applies to the following versions.

• Relativity Identity Service, version 26.x.y and later.
• Internet Information Services (IIS) 10 or later.
• Microsoft SQL Server with the EDDS database.

Prerequisites

Confirm the following before troubleshooting any application issue:

1. The installation completed successfully. If installation did not complete, see the Installer troubleshooting guide.
2. You have local Administrator privileges on the Next Gen Identity Server host.

Identifying the failing component

The Next Gen Identity Server exposes two health endpoints. https://[domainname]/RIS/Healthcheck is the service self-check; https://[domainname]/RIS/Diagnostics validates dependencies (EDDS database and Secret Store). Open both from a browser on the Next Gen Identity Server host. Then use the following table to find the right section.

IIS issues

IIS hosts the Next Gen Identity Server as an ASP.NET Core application. It runs in out-of-process mode. The service requires two IIS objects to operate:

IIS issues typically fall into two categories: HTTP browser errors, and application pool failures.

HTTP errors in the browser

The following table lists common HTTP error codes and their resolutions.

Application pool problems

The following table lists symptoms and resolutions for application pool failures.

IIS configuration commands

Use the following commands to verify the Next Gen Identity Server IIS configuration.

# Verify the Identity application pool exists and is running
Import-Module WebAdministration
Get-IISAppPool -Name 'Identity' |
    Select-Object Name, State, ManagedRuntimeVersion, AutoStart

# Verify the Next Gen Identity Server IIS application exists and points to the correct folder
Get-WebApplication -Site 'Default Web Site' |
    Select-Object Path, ApplicationPool, PhysicalPath

# Verify HTTPS binding on the site
Get-WebBinding -Name 'Default Web Site' |
    Where-Object { $_.protocol -eq 'https' } |
    Select-Object protocol, bindingInformation

# Review the most recent service log for startup errors
Get-ChildItem 'C:\Program Files\Relativity Identity Service\logs\stdout*.log' |
    Sort-Object LastWriteTime -Descending | Select-Object -First 1 | Get-Content -Tail 50

Database issues

The Next Gen Identity Server connects to the EDDS database. It reads instance settings, Secret Store data, and deployment logs.

Testing SQL Server connectivity manually

To validate EDDS connectivity, see How to conduct a UDL test on the Relativity Community site.

Secret Store issues

The Next Gen Identity Server retrieves sensitive configuration values from the Relativity Secret Store. These include token signing keys and cookie encryption keys.

Secret Store connectivity test

See the Relativity Secret Store documentation to verify connectivity and confirm the store is unsealed.

Certificate issues

The Next Gen Identity Server uses two types of certificates that serve different purposes. Identify which one is failing before troubleshooting.

Browser certificate warnings

Browser warnings appear when a user opens the Next Gen Identity Server URL and indicate a problem with the TLS/HTTPS certificate on the IIS binding.

OpenTelemetry and observability issues

Environment Watch environments only. If Environment Watch is not deployed in your environment, skip this section and see Accessing service logs without Environment Watch below.

The Next Gen Identity Server exports telemetry to an OTLP-compatible collector configured during installation.

Accessing service logs without Environment Watch

If Environment Watch is not deployed, the Identity Service writes log output to an IIS stdout log file. This file is not enabled by default. Follow these steps to enable it, read the logs, and then disable it when done.

Step 1 - Enable stdout logging

Open C:\Program Files\Relativity Identity Service\web.config in a text editor (run the editor as Administrator). Find the <aspNetCore> element and set stdoutLogEnabled="true":

<aspNetCore ... stdoutLogEnabled="true" stdoutLogFile=".\logs\stdout" ...>

Save the file and recycle the Identity application pool in IIS Manager to apply the change.

Step 2 - Reproduce the issue

Open a browser on the Identity Server host and navigate to https://localhost/RIS/Healthcheck. The service writes log entries as requests are processed.

Step 3 - Read the log

Open the most recent log file:

Get-ChildItem 'C:\Program Files\Relativity Identity Service\logs\stdout*.log' |
    Sort-Object LastWriteTime -Descending | Select-Object -First 1 | Get-Content -Tail 100

Look for lines containing Error, Exception, or Fatal. Common startup failures: unreachable SQL Server, unreachable Secret Store, missing Relativity machine certificate.

Step 4 - Disable stdout logging when done

Set stdoutLogEnabled="false" in web.config and recycle the Identity application pool. Leaving stdout logging enabled fills the disk over time.

Rolling back to Identity Server 3

Use this procedure for authentication issues after switching to Next Gen Identity Server. Apply it when other steps in this guide have not resolved the issue.

When to use this procedure

Roll back if you experience authentication failures or unexpected sign-in behavior. Use this procedure when other steps in this guide do not resolve the issue. Rolling back returns the environment to the legacy IS3 flow while you investigate.

How the rollback works

A single instance setting, IdentityProviderURL, controls which identity server handles authentication:

• Populated - Authentication routes to Next Gen Identity Server.
• Empty - Authentication uses the legacy Identity Server 3 flow.

To roll back, clear the IdentityProviderURL value. No separate rollback feature exists. Clearing this setting is the rollback.

Restart IIS on the Relativity web server after the change. The Relativity web application reads the IdentityProviderURL instance setting. Clearing it takes effect only after IIS restarts on that server. This also ends existing user sessions. Users must re-authenticate after the rollback. Notify users before performing this step during business hours.

Rollback steps

Use the following steps to revert to Identity Server 3.

1. In Relativity, navigate to Administration > Instance Settings. Search for IdentityProviderURL and open it.
2. Clear the value so the setting is empty.
3. Restart IIS on the Relativity web server (iisreset) to clear the cached IdentityProviderURL setting and authentication state.
4. Verify that users can sign in using the legacy IS3 flow.

Contacting Relativity Support

If this guide does not resolve the issue, contact Relativity Support. Provide the following information:

1. The exact symptom observed, including any error message, screenshot, and the URL accessed.
2. The response from both endpoints: https://[domainname]/RIS/Healthcheck and https://[domainname]/RIS/Diagnostics.
3. The 200 most recent lines from the latest stdout*.log file in C:\Program Files\Relativity Identity Service\logs\.
4. A browser HAR (HTTP Archive) file, if the browser can reproduce the issue. To capture a HAR file: open browser DevTools and select the Network tab. Reproduce the issue, then right-click and select Save all as HAR with content.
5. Events from Event Viewer > Windows Logs > Application during the time the issue occurred.