Documentation Plugins AWS IoT TwinMaker Troubleshooting

Troubleshoot AWS IoT TwinMaker issues

This document provides solutions to common issues you may encounter when configuring or using the AWS IoT TwinMaker app. The sections follow the order in which you set up and use the app: configuration, connection, queries, panels, and alert rules. For configuration instructions, refer to Configure the AWS IoT TwinMaker app and data source.

Configuration errors

These errors occur on the data source configuration page, and usually involve the workspace selection or the IAM role’s Amazon Resource Name.

“Assume Role ARN is required”

Symptoms:

• Save & test fails with Assume Role ARN is required.
• The configuration page shows an error alert titled Assume Role ARN.

Cause: The data source requires an IAM role to narrow its permission scope, because the resolved credentials are also used in the browser by the Scene Viewer and Video Player panels.

Solution: Create an IAM role for your TwinMaker dashboard and enter its ARN in the Assume Role ARN field.

“Missing WorkspaceID configuration”

Symptoms:

• Save & test fails with Missing WorkspaceID configuration.

Cause: The data source doesn’t have a workspace selected. This error is expected on the first save, before you select a workspace.

Solutions:

1. Click Save & test to save the connection details.
2. Open the Workspace drop-down in the Twinmaker Settings section and select your workspace.
3. Click Save & test again.

“Save the datasource first to load workspaces”

Symptoms:

• The Workspace drop-down shows this message instead of your workspaces.

Cause: The workspace list is fetched through the saved data source, so unsaved connection details can’t be used.

Solution: Click Save & test, then reopen the Workspace drop-down. If the drop-down shows Error listing workspaces, verify your credentials, Region, and IAM role permissions include iottwinmaker:ListWorkspaces.

Connection errors

These errors occur when Grafana can’t reach AWS endpoints.

Connection timeouts from Grafana Cloud

Symptoms:

• Save & test times out or fails with network errors on a Grafana Cloud stack.

Possible causes and solutions:

Custom endpoint conflicts

Symptoms:

• The connection fails when both a custom endpoint and an Assume Role ARN are configured.

Cause: You can’t currently set an Assume Role ARN and a custom Endpoint together.

Solution: Remove the custom endpoint unless you’re an AWS developer testing against a non-production endpoint.

Query errors

These errors occur in the query editor or when a panel runs a query.

Query fails with a “missing” parameter error

Symptoms:

• The query fails with one of the following errors: missing entity parameter, missing component parameter, missing property, or missing entity id & component type id - either one required.

Cause: The selected query type requires a field that isn’t set. For example, Get Property Value History by Entity requires an Entity and Component Name, and the history query types require at least one property in Selected Properties.

Solution: Set the required fields for the query type. Refer to AWS IoT TwinMaker query editor for the fields each query type requires.

List queries fail with an “error loading” message

Symptoms:

• A query or a query editor drop-down fails with an error such as error loading workspaces, error loading scenes, error loading entities, or error loading componentTypes.

Possible causes and solutions:

Scene Viewer issues

These issues occur in the Scene Viewer panel.

Scene Viewer panel fails to render on Grafana v13

Symptoms:

• The Scene Viewer panel stops rendering after an upgrade to Grafana v13.0 or later, while other panels on the dashboard keep working.

Cause: Grafana v13.0 upgraded the core application from React 18 to React 19, and the Scene Viewer panel depends on React APIs that were removed in React 19. This is a known breaking change in Grafana v13.0, not a configuration problem.

Solutions:

• Remove the Scene Viewer panel from dashboards until a compatible version of the app is released. This is the interim measure recommended by the plugin team.
• On self-managed Grafana, remain on Grafana v12.x until a compatible version of the app is released, then upgrade both together.
• On Grafana Cloud, where you can’t roll back the Grafana version, track the status of a fix in the React 19 compatibility issue and update the app when a compatible release is available.

Scene doesn’t load

Symptoms:

• The panel stays blank or shows a loading error.

Solutions:

1. Verify the selected data source and scene belong to the same workspace.
2. Verify the IAM role grants read access to the Amazon S3 bucket for the workspace, where scene assets are stored.
3. Check the browser console for errors from blocked network requests to Amazon S3.

Tags don’t change icons based on data

Symptoms:

• The scene loads, but tag icons don’t reflect property values.

Possible causes and solutions:

Video Player issues

These issues occur in the Video Player panel.

Video not available

Symptoms:

• The player shows an error screen that video isn’t available for the selected time.

Possible causes and solutions:

Alarm Configuration panel issues

These issues occur in the Alarm Configuration panel.

Panel shows warnings instead of alarm details

Symptoms:

• The panel shows TwinMaker Data Source Connected followed by a Warnings: line instead of the alarm ID, threshold, and notifications.

Possible causes and solutions:

Can’t edit the alarm threshold

Symptoms:

• Saving a new threshold in the Edit Alarm dialog box has no effect, or the logs show writer role not configured or assume role ARN Write is missing in datasource configuration.

Cause: Alarm edits write to your workspace with the BatchPutPropertyValues API, which requires a separate write role that isn’t configured on the data source.

Solution: In the data source configuration, switch on Define write permissions for Alarm Configuration Panel and enter the IAM role in the Assume Role ARN Write field. The role must grant the iottwinmaker:BatchPutPropertyValues action. Refer to Configure the AWS IoT TwinMaker app and data source.

Alert rule errors

These errors occur when you use the data source in alert rules.

Alert rule fails to evaluate a query that works in a panel

Symptoms:

• A query returns data in a dashboard panel, but the same query fails with a data format error when you use it in an alert rule.

Cause: Alert conditions can only evaluate numeric data. Queries that return string values, such as a Get Alarms query or a property history query for a string property like alarm_status, can’t be reduced to a number for the alert condition.

Solution: Create the alert rule against a numeric property instead, such as the sensor value that drives the alarm. Refer to AWS IoT TwinMaker alerting for query guidelines and examples.

Enable debug logging

To capture detailed error information for troubleshooting on self-managed Grafana:

1. Set the Grafana log level to debug in the configuration file:

   ini Copy

   [log]
   level = debug

2. Review the logs for entries from the grafana-iot-twinmaker-datasource backend plugin.

3. Reset the log level to info after troubleshooting to avoid excessive log volume.

Get additional help

If you continue to experience issues after following this troubleshooting guide:

1. Check the AWS IoT TwinMaker documentation for service-specific guidance.

2. Review the Grafana community forums for similar issues.

3. Review the plugin’s GitHub issues for known bugs, or open a new issue.

4. Contact Grafana Support if you are a Cloud Pro, Cloud Contracted, or Enterprise user.

5. When reporting issues, include:

   • Grafana version
   • Plugin version
   • Error messages (redact sensitive information)
   • Steps to reproduce
   • Relevant configuration, such as the authentication provider, Region, and IAM role setup (redact account IDs, role identifiers, and other credentials)