Skip to main content

Troubleshooting

This guide covers common issues and solutions for the OctoMesh Power BI Connector.

Connector Not Visible in Power BI Desktop​

  1. Verify the .pqx file is in the correct Custom Connectors folder: 
    C:\Users\<YourUsername>\Documents\Power BI Desktop\Custom Connectors
  2. Check that Allow any extension to load is enabled:
    • Go to File > Options and settings > Options
    • Under Security > Data Extensions, select Allow any extension to load without validation or warning
  3. Restart Power BI Desktop completely.

Connector Not Visible in Gateway​

  1. Verify the connector is installed in the Gateway's Custom Connectors folder: 
    C:\Windows\ServiceProfiles\PBIEgwService\Documents\Power BI Desktop\Custom Connectors
  2. Check that the Gateway service has been restarted after copying the connector.
  3. Ensure Allow user's custom data connectors is enabled in Gateway settings in Power BI Service.
  4. Open the Gateway application and check the Connectors tab.

Connector Not Visible in Power BI Service​

  1. Verify the connector appears in the Gateway application's Connectors tab.
  2. Check Gateway settings in Power BI Service:
    • Settings > Manage connections and gateways
    • Select Gateway > Settings
    • Enable Allow user's custom data connectors to refresh through this gateway cluster
  3. Restart the Gateway service and refresh the page.

Authentication Errors​

OAuth (Desktop)​

  1. Clear existing credentials:
    • File > Options and settings > Data source settings
    • Find the OctoMesh connection and click Clear Permissions
  2. Re-authenticate by connecting again.

Client Credentials (Service)​

  1. Verify the Client ID and Client Secret are correct.
  2. Ensure the service account has the required scopes:
    • assetTenantAPI.full_access
  3. Verify the service account has access permissions for the tenant.
  4. Check if the client secret has expired.

Connection Test Fails​

  1. Verify the Asset Repository URL is correct and accessible:
    • Try opening the URL in a browser
    • Check for typos (e.g., https:// not http://)
  2. Check that the Tenant ID exists and you have access.
  3. Verify the Runtime Query ID is valid:
    • Open OctoMesh and check the Runtime Query exists
    • Ensure your credentials have access to the query

Gateway Shows "Local Network Problems" or "Not Reachable"​

If the Gateway application shows the connector is correctly configured but reports network problems:

1. Check Gateway Status​

Open the Gateway application - it should show "Ready" status. If not, the Gateway has connectivity issues to Power BI Service.

2. Verify Firewall Settings​

The Gateway requires outbound connections to:

DomainPorts
*.servicebus.windows.net443, 5671, 5672
*.frontend.clouddatahub.net443
login.microsoftonline.com443
*.analysis.windows.net443
*.pbidedicated.windows.net443

3. Check Gateway Logs​

Look for errors like Invalid relays parameter in the Gateway logs:

C:\Windows\ServiceProfiles\PBIEgwService\AppData\Local\Microsoft\On-premises data gateway\Report

4. Reset the Gateway​

If the problem persists, a complete reset may be necessary (see below).

Resetting the Gateway​

If the Gateway has persistent configuration issues:

Step 1: Stop the Gateway Service​

  1. Open services.msc
  2. Find "On-premises data gateway service"
  3. Click Stop

Step 2: Remove Gateway from Power BI Service​

  1. Go to Power BI Service
  2. Navigate to Settings > Manage connections and gateways
  3. Select your Gateway cluster
  4. Click Remove or Delete

Step 3: Delete Local Gateway Configuration​

Delete or rename this folder:

C:\Windows\ServiceProfiles\PBIEgwService\AppData\Local\Microsoft\On-premises data gateway

Step 4: Re-register the Gateway​

  1. Open the Gateway application (as Administrator)
  2. Sign in with your Power BI account
  3. Select Register a new gateway on this computer
  4. Provide a name and save the Recovery Key securely

Step 5: Re-install the OctoMesh Connector​

  1. Copy OctoMeshConnector.mez or .pqx to: 
    C:\Windows\ServiceProfiles\PBIEgwService\Documents\Power BI Desktop\Custom Connectors
  2. Restart the Gateway service

Step 6: Re-configure Gateway Settings​

  1. Open Power BI Service
  2. Go to Settings > Manage connections and gateways
  3. Select your new Gateway > Settings
  4. Enable custom connectors (see Gateway Setup)

Refresh Fails in Power BI Service​

  1. Check the refresh history for error details:

    • Semantic Model settings > Refresh > Refresh history

  2. Verify the Gateway connection:

    • Semantic Model settings > Gateway and cloud connections
    • Ensure the data source is mapped to a connection

  3. Test the connection in Power BI Service:

    • Settings > Manage connections and gateways
    • Select the connection > Test connection

  4. Check Gateway status:

    • Open the Gateway application on the server
    • Verify it shows "Ready"

Data Not Updating​

  1. Check if refresh is scheduled:

    • Semantic Model settings > Refresh > Scheduled refresh

  2. Verify the Runtime Query returns current data:

    • Test the query in OctoMesh directly

  3. Check refresh history for any failures.

  4. Manually refresh to test:

    • Workspace > Semantic Model > Refresh now