Troubleshooting

This page is organised by symptom: find the heading that matches what you or your users are seeing, then work through the causes in the order given, most likely first.

Before you start

• Open the host's page (Catalog → Hosts) and press Connect. Many problems show up there as a plain sentence: a missing role, a pending restart, a licensing problem.
• Note who is affected. One user, everyone except administrators, or everyone? On one host or all of them? The answer usually points straight at the cause. A problem that seems to depend on where somebody is (in the office or at home) almost never does: DartRelay connects to the host from the DartRelay server, wherever the browser is, so look at which account was used in each test instead.
• Check the logs. A launch the host refuses is written to the log with the user, the application and the reason. See Logs and audit.

A host is not ready

The Readiness column on the Hosts list, and the verdict on the host's page, show a warning instead of the ✔.

"No RD Session Host role"

Cause: the host is in Windows' administration mode, which allows two connections. Fix: install the role from the host's page. See Install the Remote Desktop Session Host role.

"⚠ Restart needed"

Cause: the role is installed but Windows has not restarted, so the host still behaves as if it had no role. Fix: restart the host. The warning clears by itself the next time a page showing the host is opened. If it does not, open the host page: Already restarted, and still no role? lets you run the install again safely.

"This host has not been checked" or "the role state could not be determined"

Cause: nobody has pressed Connect, or the account worked but the host's registry could not be read. Fix: press Connect. If the role still cannot be determined, make sure the Remote Registry service is running on the host and TCP 445 is open from the DartRelay server, or enable the HTTPS management listener (winrm quickconfig -transport:https).

Connect fails

The licensing line warns that the grace period is ending, or the licence server cannot issue licences

Cause: the host has no working Remote Desktop licence server. When the 120-day grace period ends, it refuses everyone except administrators. Fix: configure an RDS licence server and licensing mode on the host before the countdown reaches zero. See Remote Desktop licensing.

Installing the Session Host role fails

The install itself takes several minutes and shows no percentage, only the time elapsed. That is normal; leave the page open.

Sign-in to the host fails

The application or desktop does not open, and the tab reports "Server refused connection (wrong security type?)", an authentication failure, or the portal shows a pop-up saying "You are not authorized to use this application." The browser can only report what the host said during the connection, and Windows refuses several quite different problems with the same wording. Work through these causes.

Only administrators can connect; everyone else is refused

1. The users are not allowed to sign in through Remote Desktop. A host that has just joined a domain admits only administrators. On the host page, press Let domain users sign in (in the section Users other than administrators refused with "Server refused connection"?). This adds the host's domain users to its Remote Desktop Users group. Users from another domain need their group added by hand: net localgroup "Remote Desktop Users" "OTHERDOMAIN\Domain Users" /add. See Who may sign in through Remote Desktop.
2. The licensing grace period has ended. An expired grace period refuses everyone except administrators. Press Connect on the host page and read the licensing line. On the host, Windows records this in the TerminalServices-RemoteConnectionManager event log.
3. A policy denies Remote Desktop sign-in. Check for a Deny log on through Remote Desktop Services entry, or a Group Policy that limits Remote Desktop sign-in to a group these users are not in.

One particular account is refused, on one host

• The account is not in Remote Desktop Users on that host (other hosts may have it).
• The account must change its password at next sign-in, is locked or disabled, or the saved password on a Fixed Credentials resource is out of date.
• For a person from another domain: the host does not trust their domain, or their group has not been added to Remote Desktop Users. See Active Directory and multiple domains.

Every launch on a stand-alone host is refused, even with the right password

Cause: the host is not in a domain, and no domain is being sent with a local account. Windows refuses a local account with an empty domain when Network Level Authentication is on. Fix: put the host's computer name in the host's Domain field, or write the saved account as COMPUTERNAME\user. When the host is the same machine DartRelay runs on, DartRelay fills in the machine name for you. See The Domain field.

"You are not authorized to use this application" New in 2.0

When the host itself refuses the account, the tab closes and the portal shows this message with the application's name, instead of an error inside the tab. The real reason the host gave is written to the log as a warning from the portal launch, naming the user, the application and the code. Look there first, then work through the causes above.

The application does not open

The tab shows "<application> has not appeared" New in 2.1

The session connected, but the application's window was not shown within the expected time. The panel offers Keep waiting and Close. If the window turns up later, the panel removes itself.

1. Windows is waiting for an answer nobody can see. If the account has two or more disconnected sessions on the host, Windows asks "Select a session to reconnect to", which a published application cannot show; after about half a minute Windows gives up. On the host page, set End disconnected sessions after (1 hour is recommended), then press Sign out disconnected sessions. See Ending disconnected sessions.
2. The program only allows one copy of itself and is already running in the session, so it started nothing new. Use the tab that already has it, and close the empty one.
3. The program shows nothing at first. Some programs take a long time to start or open no window of their own straight away. Press Keep waiting.

The session opens and closes again straight away

• The program hands over to something else and exits. Windows ends a remote application's session when its program exits. On Windows Server 2022, calc.exe is such a program; it is why Calculator is not offered there. Publish the program that actually stays running.
• The program could not be registered on the host. If the app group's last save showed an amber message, the host may refuse the program as not allowed. Fix what the message named (usually the host's management account) and save the group again. See There is no Publish button.
• The path is wrong. Check that the program path on the row exists on the host. A program installed in one person's own profile only works for that person.

An accessory does not open

An accessory (such as the Math Input Panel or On-Screen Keyboard) opens over an application the person already has open, and only one from the same app group on the same host.

• "Start the application you want to use it with, then open this." Nothing is open for it to appear over. Open the main application first.
• "It is published separately…" Something is open, but from a different app group. Publish the accessory in the same group as the applications it is used with. See Accessories.

The second copy of a program opens an empty tab

Opening a program twice normally gives a second copy in a second tab. A program that allows only one copy of itself cannot do that, so the second tab stays empty. Close it; the first tab is unaffected.

Sessions freeze, or a second application turns black

The second or third application stays black, or appears inside the first tab

Occasionally, when a second or third application joins an open Windows session, the session stops responding: the new application stays black or shows the has not appeared panel, and the other tabs for that host stop responding too. This is a known issue being worked on. Workaround: close every tab for that host and open the application again, which starts a fresh connection. If it happens often, email support with the time it happened so the logs can be matched.

A tab joining from a second browser freezes

Earlier versions could also freeze when the same person joined an open session from a second browser or a private window. This was fixed in version 1.9.

Opening on another device ends the session on the first

This is Windows allowing one session per account, not a freeze. Choose the behaviour you want under Sessions for the same person.

A user cannot see an application

1. Access rules. Open the resource and check its Access Control. With Only Allowed, the person, or a group they are in, must be listed. See Giving people access to resources.
2. Restricted categories. A resource filed only in categories the person cannot see is hidden from them. Look for the Restricted badge on Catalog → Categories. See Restricted categories.
3. Group membership could not be read. If the portal tells the person that resources granted through a group will not appear, DartRelay could not reach their domain to read their groups, often because they typed a domain name that does not exist (an old or mistyped short name). See Active Directory and multiple domains.

Browsing a host finds too few programs, or no icons

DartRelay does not start after installation, and there is no log

If DartRelay's services never start and its log folder is empty, the failure happened before DartRelay could write anything. The Windows Application event log (Event Viewer → Windows Logs → Application) is then the only record, and it names the faulting component.

Versions before 1.4 could fail this way on recent processors with Windows' hardware-enforced stack protection, showing an assertion mentioning AreShadowStacksEnabled when run by hand. Current versions are not affected; upgrade. To confirm the diagnosis on an old version without upgrading, turn Hardware-enforced Stack Protection off for DartRelay's web executable under Windows Security → App & browser control → Exploit protection → Program settings.

Related pages