🛠️ Support and Troubleshooting

This section covers diagnostic procedures for the most common PowerConnect issues — endpoint connectivity, MDX queries, and authentication errors — with the steps you can follow before opening a support ticket.

What you'll find in this section

Hitting the /environments endpoint

Direct testing of PowerConnect's /environments REST endpoint to verify the service is reachable and configured correctly.

Why it matters: confirms the service is responding before you spend time debugging on the Power BI side. If /environments doesn't return what you expect, the problem is server-side, not BI-side.

Hitting the /instances endpoint

Direct testing of the /instances endpoint to verify which TM1 instances PowerConnect can see for a given environment.

Why it matters: a quick check that the connections defined in settings.yml are actually wired up and reachable from the PowerConnect host.

Troubleshooting MDX

Diagnostic steps for MDX queries that return errors or unexpected results when used through PowerConnect.

Why it matters: most data-shape issues turn out to be MDX issues. This article makes that hypothesis quick to test and rules out PowerConnect itself as the cause.

Problems with Authenticating with the Organizational Account

How to resolve OAuth2 authentication errors against Microsoft Azure AD — typically caused by a misconfigured Client ID or Client Secret during App Registration.

Why it matters: this is the most common single error during initial setup. The article gets people unstuck without an Azure admin in the room.

Setting up PowerConnect

💡 If PowerConnect won't start, do this first. Run the server executable directly from the PowerConnect installation folder — cwpapbiserver.exe on Windows, ./cwpapbiserver on Linux. It runs in the foreground and prints the actual error, which is usually the fastest clue to what's wrong. Then use the tables below to match that error to a likely cause and solution. (Only needed when PowerConnect fails to start — not during normal operation.)

Windows Setup — common problems

Symptom	Solution

Symptom	Solution
Service won't start — "port already in use"	Another program is using the port. Change the `port` in `conf/settings.yml` (e.g. `8000`), or free the port, then restart the service.
"Settings file not found"	This is rare — PowerConnect normally recreates the settings file automatically. Restart the service; if it persists, contact support.
License error on startup	Place a valid `License.xml` in the `conf` folder, then restart the service.
Service won't start when HTTPS is enabled	Make sure your certificate files are present in `conf/ssl`, or set `usessl: false` to confirm the rest of the setup works.
Can't sign in with the Organizational Account	Check your Azure Client ID, Client Secret and Tenant ID — see Problems with Authenticating.
Connector changes don't appear in Power BI	Replace the connector file in `%APPDATA%\Microsoft\Power BI Desktop\Custom Connectors\` and fully restart Power BI Desktop.
Power BI or other machines can't reach the service	Allow the configured port through the firewall.

Linux Setup — common problems

Symptom	Solution

Symptom	Solution
Service won't start / keeps restarting, creating many empty `app_*.log` files	The license validator usually isn't executable. Make it executable: `sudo chmod +x /opt/powerconnect/bin/validator.exe`, then restart. If it still fails, check the error with `sudo systemctl status PowerConnectService` and `sudo journalctl -u PowerConnectService`, and match it to a row below.
PowerConnect starts and then stops automatically	The port may already be in use by another program (same as on Windows). Change the `port` in `settings.yml`, or free the port, then restart.
Service stops with a permission error about the service user's home folder	Create a home folder for the service user, then restart.
`setup.sh` reports "command not found" or "bad interpreter"	Make it executable and use Unix line endings: `chmod +x setup.sh` and `sed -i 's/\r$//' setup.sh`.
Service can't write its files or start	Install under `/opt` and give the service user ownership of the install folder.
License not found on startup	Place `License.xml` in the `conf` folder, alongside `settings.yml`.

Summary

When PowerConnect isn't behaving the way it should, these articles work outwards from the simplest checks (is the service responding?) through to the most common authentication failures. Working through them in order resolves the majority of issues without escalation.