Troubleshooting the Workstation Client

Last modified: October 5, 2026

Introduction

This document provides troubleshooting instructions for some potential issues related to the Workstation Client.

Logs

By default, the Client retains logs of up to 10 MB for the past seven days locally on your computer. To access the logs, open the Client and select the Logs option from the three dots menu in the top right corner, then optionally select the level of logs you want to see.

Log files are also available by day in the Client's app data folder. On Windows, press Win + R and enter:

  • If you installed the Client using the installer for all users: %ProgramData%\Mendix Workstation\logs
  • If you are using the portable version: %AppData%\Mendix Workstation\logs

On Linux, the Mendix Workstation/logs folder is located at either $XDG_CONFIG_HOME or ~/.config.

Live logs are available in two ways:

  • Start the Workstation Client. Click the three-dot icon in the top tight, then click Logs. Debug level logs are only available in Developer Mode
  • Start the Workstation Client from PowerShell: start "C:\Program Files\Mendix Workstation\Mendix Workstation.exe" -ArgumentList "--log-level=debug" -wait.

Diagnostics

When Developer Mode is enabled, the Client also shows a Diagnostics page. This page displays information about the available devices, credentials, station configuration, system info, and log levels, which you can use to help you troubleshoot any issues.

You can also view some diagnostics in Workstation Management, without access to the computer and regardless of whether Developer Mode is enabled. For more information, see the Client Diagnostics section in Managing Stations.

Safe Storage Is Unavailable

The Client does not start and shows the following error: Safe storage is unavailable. Install or unlock the system keyring and retry. On Linux, the computer may also show a prompt to unlock the keyring.

Cause

The Client encrypts its API key with the secret store of the operating system, and cannot start without it. On Linux, the secret store is the keyring of the desktop environment, which is usually unlocked with the password that the user enters at login. The Client cannot start in the following cases:

  • The keyring is not installed.
  • The keyring is locked.
  • The desktop environment provides no supported keyring. This can be the case with minimal kiosk sessions.
  • The Client is started from an SSH session. No desktop login takes place, so the keyring may not be running or may be locked.
  • The computer logs in automatically, for example a shop floor computer in kiosk mode. No password is entered at login, so the keyring stays locked and the operating system prompts for its password. On an unattended computer, nobody enters it, and the Client does not start.

Solution

Depending on the cause, use one of the following approaches. For the exact steps, see the documentation of your Linux distribution, desktop environment, or keyring.

Keyring Not Installed, Locked or Unsupported

Install a supported keyring. On Linux, ensure that the keyring is unlocked. After installing or unlocking the keyring, start the Client again.

Client Started from an SSH Session

Before you start the Client, start the keyring service in the SSH session and unlock it with the password of the user. Alternatively, log in to the desktop session of the user on the computer, which unlocks the keyring, and then start the Client.

Computer Logs in Automatically

Configure the login of the computer so that it unlocks the keyring.

Client Must Be Registered Again

After a change to the computer, a previously registered Client shows the registration screen again.

Cause

The API key of the Client can only be decrypted with the secret store that encrypted it. If the secret store changes, the Client cannot read its credentials. This happens in the following scenarios:

  • The configuration folder is copied between computers or into an image, for example for a shared installation.
  • A computer is replaced and its configuration folder is restored from a backup.
  • An administrator resets the password of the user, for installations per user.
  • The keyring changes on Linux.
  • The Client is downgraded from version 4.3 to a lower version.

Solution

Register the Client again. For more information, see Registering Workstation Clients.

Registration Token Could Not Be Parsed

The Client shows an error like the following: Registration token could not be parsed. Please enter another token!

Cause

You entered a registration token with an invalid format.

Solution

Ensure you copied and pasted the token exactly as displayed in Workstation Management without any additional characters. Create a new registration token if the issue persists.

Registration Token Denied by Workstation Management

The Client shows an error like the following: Registration token denied by Workstation Management. Please use another token.

Cause

The registration token is no longer valid. This can occur if:

  • The token expired after one hour
  • The token was recreated in Workstation Management (using the Refresh button or reopening the registration window)
  • The token has already been used by another Workstation Client

Solution

If the station status in Workstation Management is still No computer registered, regenerate the token and try again. Otherwise, verify the correct computer and Client are registered to that station and unregister if not.

HTTPError: Request failed with status code 503 Service Temporarily Unavailable

The Client shows an error like the following: Station could not be synchronized with Management. Error invoking remote method 'refresh-station-config': HTTPError: Request failed with status code 503 Service Temporarily Unavailable: GET.

Cause

Workstation Management is temporarily offline, most likely due to maintenance.

Solution

Check out the Mendix Status Page to see if there is a scheduled maintenance for the Workstation Management. If there is no maintenance message and the issue persists after a few minutes, report an incident via the status page.

TimeoutError: Request timed out

The Client shows an error like the following: Station could not be synchronized with Management. Error invoking remote method 'refresh-station-config': TimeoutError: Request timed out: GET [yourStationURL]

Cause

The Client request to Workstation Management is not forwarded to the Workstation Management server and times out. This issue may occur if your network traffic is routed through a proxy server, as is common in protected corporate IT environments, and the proxy server is offline.

Solution

Verify whether your computer's network traffic is routed through a proxy server and configure your proxy settings accordingly. See Network Configuration.

Workstation Management URL cannot be resolved

The Client shows an error like the following: Station could not be synchronized with Management. Error invoking remote method 'refresh-station-config': Error: Workstation Management URL cannot be resolved. This might be an DNS issue or the host is offline.

Cause

The Client cannot resolve the URL to Workstation Management. This can have several causes, most commonly when the machine running the Workstation Client has no internet connection.

Solution

First, verify you have a working internet connection. Then verify you can access Workstation Management from your browser. If your browser cannot resolve that address, there may be an issue with your DNS server or configuration. On Windows, verify your DNS settings for your Ethernet or wireless LAN adapter using the command prompt and entering ipconfig. The command nslookup www.mendix.com provides further information about the IP address your DNS server resolved for the Mendix domain.