Skip to main content

Reference articleTroubleshooting Guide for End-users

  • Updated

Troubleshooting Guide for End-users

This guide provides a checklist of common issues that you, an end-user, may encounter at each stage, when you are attempting to:

  • log in to your corporate Tehama Portal,
  • find an entry for your Tehama virtual desktop in the portal, and
  • connect to your Tehama virtual desktop.

What should happen:

  • you are successfully logged in to your corporate Tehama Portal,
  • you are able to find your desktop in the portal, and
  • you are able to connect to your desktop and see it on your screen.

But instead of a desktop session, you are stuck somewhere along the journey. You see an error message, or something does not happen when it should.

This guide runs through issues you may encounter and the remediation steps you can attempt:

1. Can you not log in to your corporate Tehama Portal?

Common login issues:

  • You are unable to join/register with Tehama. (See Join Tehama for End-users.)
  • When you try to log in (see Login instructions), you:
    • see 'wrong password' or 'password expired' messages.
    • see 'wrong Multi-factor Auth (MFA) code' messages.
    • For organizations with Single Sign-On (SSO) enabled, fail to be logged in automatically.
  • You see a dialog asking you for your organization's subdomain instead of the LOG IN dialog.

What to try:

  • If you never completed joining/registering with Tehama, do that now. (See Join Tehama for End-users). If the link in your "Welcome to Tehama" email does not work or has expired, ask your employer or Tehama Support to resend the invitation email to you so you can try again.

  • Make sure you have the correct subdomain for your employer's organization in the Tehama Web UI login URL. The subdomain is the part of the URL before "tehama.io" in the login URL.
    can't remember your tehama organization subdomain?
    • go to https://app.tehama.io/ and click on can't remember your organization's url?
    • enter your email and click on submit. your organization's login url will be emailed to you. the subdomain is the part of the url before "tehama.io".
  • Make sure you are using the correct credentials (Google auth vs Multi-Factor auth). You cannot use Google auth if you joined Tehama through Multi-Factor Auth and vice versa.
  • Are you using Multi-Factor Auth and forgot your password, or it is expired? Click on the "Forgot your password?" link, enter your email in the FORGOT YOUR PASSWORD dialog and click SUBMIT. A reset password link will be sent to your email. Click on the link to reset the password. (You can also ask your employer to initiate a password reset for you.)

  • Are you using Google Auth or SSO and forgot your password, or it is expired? Follow the reset password instructions for Google or your Identity Provider, respectively.

  • Are you using Multi-Factor Auth and your MFA code is not valid? Ask your employer to initiate a reset of your MFA code. The next time you try to log in, you will be prompted to reset your code.

  • Are you using SSO and login is failing? Ask your employer to verify that your user in the company’s Identity Provider has been added to the Tehama application.

  • It is possible that when you joined/registered with Tehama, the process did not complete successfully. Ask your employer or Tehama Support to verify that the status of your user in Tehama is "Active" and not "Pending". If it is "Pending", ask them to resend the invitation email to you and try again.

  • Still cannot log in? Ask Tehama Support for help.

2. Can you not find your desktop entry in the portal?

Common missing desktop issues:

  • You cannot find the correct page from which to see the list of your desktops in the corporate Tehama Portal. (Desktop entries are found on the DESKTOPS page.)
  • You do not see your desktop in the list of desktops.
  • You see no desktop entries.

What to try:

  • Be sure you are on the DESKTOPS page in the portal:
    • Click on the DESKTOPS tab in the navigation bar to get to the DESKTOPS page.
      • Be aware that Staff members (most end-users are Staff members) typically land on the DESKTOPS page after logging in to the portal, but managers and admin users will land on the ROOMS page.
      • Expand the navigation bar to be sure the icon you are selecting is DESKTOPS.
    • Be sure you are viewing the "DESKTOPS" option on the page. (The options are "DESKTOPS" and "IMAGES".)

  • Look at the top of the DESKTOPS page to see if you have multiple views available to you: "In use", "My Desktops" or "All Desktops". (Only managers or admins will have these options.) Be sure you are viewing "My Desktops", in order to see the list of desktops assigned to you.

  • Refresh your browser page. If the desktop was created recently, it may now show up.

  • Ask your employer to confirm the name of your desktop, or if you have been assigned to a desktop.

  • Your employer says you have been assigned to a desktop, but you still cannot see it? Ask Tehama Support for help.

3. Is the CONNECT button not clickable?

Common connect button issues:

  • The CONNECT button is greyed out.
  • The PREPARING YOUR DESKTOP dialog does not come up when you click the connect button.

What to try:

  • Look at the Status column value for your desktop's entry on the DESKTOPS page.
    • Does it say "Building"? Wait for your desktop to finish building, then try connecting again. It should not take more than 10 or 15 minutes. If it takes longer than that, ask Tehama Support to look into it.
    • Does it say "In Use" (and this is not a legacy shared desktop)? You may not have logged off successfully after your last session. Try restarting your desktop, which should take 5 or 10 minutes, then try connecting again.
    • Does it say "Available" (which is the desired state)? It may simply be an anomaly. Try restarting your desktop, which should take 5 or 10 minutes, then try connecting again.

  • Ask your employer to check if the maximum number of concurrent desktop sessions has been reached, for desktops in your desktop's Room. You may need to wait until another desktop session has ended, then try to connect again.

  • Still getting no action from the CONNECT button? Ask Tehama Support for help.

4. Are you having Room Policy Issues?

Common room policy issues:

  • When you click on the CONNECT button, you see a message saying you need to accept the Room policy.
  • When you click on the CONNECT button, you see a message saying you are in violation of the Room policy.

What to do:

  • If told you must accept the policy:
    • Click on the name of the Room in the desktop's entry and click on the I ACCEPT button. Then return to the DESKTOPS page and try connecting again.

  • If told you are in violation of the policy:
    • Confer with your employer about the Room policy restrictions/requirements.
    • Make sure your Tehama profile is completed accurately, with fields relevant to the Room policy filled in.
    • If you are still in violation of the Room policy, you may need to request a move to another Tehama Room that has a policy that you meet.

5. Did your desktop fail to prepare?

Common issues in the desktop preparation phase:

  • You see the ERROR PREPARING DESKTOP modal.

What to do:

  • Try restarting your desktop, then try connecting again.
    • Your desktop may be having difficulty starting, or coming out of hibernation. A restart may help. It should take 5 to 10 minutes. Then try connecting again.
    • Note that restarting your desktop more than once is not useful.

  • Is your desktop still failing to prepare? Ask Tehama Support to verify the status of your desktop.

6. Did your desktop fail to launch?

Common issues in the desktop launching phase:

  • You see the ERROR LAUNCHING DESKTOP modal.
  • The LAUNCHING YOUR DESKTOP modal hangs.
  • You see the LAUNCH COMPLETE modal, but your desktop has not launched.

What to do:

  • Check that you have allowed the Tehama application that launches the Desktop to open. When launching the Desktop, your browser will display a message asking you to allow the app to open:
    • On Mac:
      Message: "Open Tehama.app?".
      Click on Open Tehama.app to allow the app to open.
    • On Linux:
      Message: "Open xdb-open?".
      Click on Open xdb-open to allow the app to open.
    • On Windows:
      Message: "Open Microsoft© Windows Based Script Host".
      Click on Open Microsoft© Windows Based Script Host to allow the app to open.

    Optional: Check the box beside the "Always allow <your corporate portal> to open links of this type in the associated app", before clicking on the Open button, to permanently allow the application to open without having to see this message again.

  • Check that your desktop session is not being blocked by your host device's antivirus software.
    • Look to your antivirus software's support to determine how to see what it may be blocking, and how to safe-list the Tehama Client software.
    • If it is found to be blocking your desktop session from launching, safe-list the relevant applications and then try connecting again.

  • Restart the desktop and try connecting again.
    • Restart can take 5 to 10 minutes.

  • Check your Tehama Client Version and compare it to the currently available Tehama client version (see the installation guides for Linux, Windows, or Mac).
    • If your client is out of date, update (uninstall your existing client then download and install an updated version) your Tehama client and try connecting again.
    • If it is not installed, install it.

  • Verify that the Tehama Client is installed correctly on your host device.
  • Check the latency between your IP location and the AWS region that contains the Tehama Room your desktop is linked to.
    • Use the tool found at: https://www.awsspeedtest.com/latency.
    • Room AWS Regions:
      • Find the name of your Room in the entry for your desktop on the DESKTOPS page.
      • Then find the entry for the Room on the ROOMS page. The entry will contain the AWS region for the room.
    • High latency could prevent your desktop from reliably launching. If latency is high, speak to your employer's internal support. You may need to request a move to a Tehama Room in a region that is closer geographically to your location.

  • Is your desktop still failing to launch? Ask Tehama Support to verify the status of your desktop. Attach the pre-session log files to the support request. Instructions to download your desktop's log files can be found here:

7. Your desktop launches, but does not log you in?

Common desktop login issues:

  • The desktop launches, but fails to log you in and closes the session.

What to try:

  • Check the latency between your IP location and the AWS region that contains the Tehama Room your desktop is linked to.
    • Use the tool found at: https://www.awsspeedtest.com/latency.
    • Room AWS Regions:
      • Find the name of your Room in the entry for your desktop on the DESKTOPS page.
      • Then find the entry for the Room on the ROOMS page. The entry will contain the AWS region for the room.
    • High latency could prevent your desktop from reliably completing the desktop log in procedure. If latency is high, speak to your employer's internal support. You may need to request a move to a Tehama Room in a region that is closer geographically to your location.

8. Is the internet connection on your desktop not working?

Common desktop session internet issues:

  • Yay! You have successfully launched your desktop, but (Oh No!) you cannot connect to the internet. E.g.: You open a browser and try to google the word “Hello” and get no results.

What to do:

  • Wait a few minutes and try accessing the internet again.
    • For the first few minutes of your session, your desktop is busy behind the scenes establishing a link with the Tehama Room your employer set up in Tehama to provide the resources and the access that you need to your company’s private network and/or the internet. (See Rooms User Guide for more information about Tehama Rooms.)
    • Until that link is established, your desktop will not be able to access the internet.
    • Once this link is established, your virtual desktop should be good-to-go.

  • Ask your employer to verify that your desktop's Room's connectivity status is green.

  • Ask your employer what firewall settings are imposed on your desktop via the desktop's Room, and what you should be able to access. Ask if Tehama's DNS Filtering feature is active in the Room, as this could be restricting access to certain domains (this feature is available only in Multi-Path Rooms).

  • Still not able to access to the internet? Or to certain websites or other resources that are permitted for your desktop? Ask Tehama Support for help.

9. Are you having trouble using one of your peripheral devices on your desktop?

Common desktop session peripheral issues:

  • Yay! You have successfully launched your desktop, but (Oh No!) you cannot use one or more of your keyboard, extended number pad, webcam, microphone, etc.

What to try:

  • Verify that your peripheral is supported by the Tehama Client at Tehama Client features (Device Support).
    • If not, and it is essential for your work, contact your employer for workarounds (like alternate peripherals etc.) that may exist.

  • Verify that your host device meets the system requirements to run the Tehama Client.
    • You may be able to launch a desktop session, but your host device may not be sufficient to support certain peripherals.
    • Upgrade or change your host device, if necessary, install the Tehama Client, and then try connecting and using the peripheral again.

  • Verify that the client installed is the latest available version.
    • Check Tehama's Release Notes to see what the latest version is.
    • Follow the instructions at Check Your Tehama Client Version to find out what version your current installation is.
    • If your version is out of date, Update (uninstall your existing client then download and install an updated version) Tehama Client and try connecting and using the peripheral again.

  • Was the client installed following the latest available installation guide?
  • Is your peripheral supported? Your Tehama Client up-to-date and installed with the latest instructions, but it still does not work? Ask Tehama Support for help.

10. Your desktop connection is really, really slow?

Common desktop session usability issues:

  • Is the desktop’s response time subpar?

What to try:

  • Check the latency between your IP location and the AWS region that contains the Tehama Room your desktop is linked to.
    • Use the tool found at: https://www.awsspeedtest.com/latency.
    • Room AWS Regions:
      • Find the name of your Room in the entry for your desktop on the DESKTOPS page.
      • Then find the entry for the Room on the ROOMS page. The entry will contain the AWS region for the room.
    • High latency could result is subpar response times. If latency is high, speak to your employer's internal support. You may need to request a move to a Tehama Room in a region that is closer geographically to your location.

11. Any other issues?

Is your issue none of the above?

What to try:

  • First check with your employer to see if this is an issue that involves something your company controls, like File Vault files, tunnels to your company’s private resources, Windows or Linux update issues, etcetera.
    • Your employer will be able to assist you with such issues.

  • Your issue appears to be Tehama-related? Ask Tehama Support for help.

Related articles