Documentation Plugins AWS IoT SiteWise Troubleshooting

Troubleshoot AWS IoT SiteWise data source issues

This document provides solutions to common issues you might encounter when you configure or use the AWS IoT SiteWise data source. For configuration instructions, refer to Configure the AWS IoT SiteWise data source.

Plugin version and compatibility issues

Many issues that appear after a Grafana or plugin upgrade come from a version mismatch between the plugin and your Grafana instance.

Check the plugin version

To find the installed plugin version:

1. Navigate to Administration > Plugins and data > Plugins.
2. Search for AWS IoT SiteWise and select the plugin.
3. Read the installed version on the plugin page. The page also lists the available versions and the Grafana version each one supports.

Verify version compatibility

The plugin requires a minimum Grafana version. The current plugin releases require Grafana 10.4.0 or later. On Grafana instances earlier than 10.4.0, use plugin version 1.25.2, which is the last version that supports earlier Grafana releases.

If your Grafana instance is earlier than 10.4.0, pin the plugin to version 1.25.2. To use a later plugin version, upgrade Grafana to 10.4.0 or later first. Always confirm the exact minimum Grafana version on the plugin page before you upgrade.

Errors after a Grafana or plugin upgrade

Symptoms:

• The data source configuration page or query editor fails to load after an upgrade.
• The browser console shows a JavaScript error, such as TypeError: Cannot read properties of undefined.
• Panels that previously worked return errors or stop rendering.

Solutions:

1. Compare the plugin version with your Grafana version against the compatibility table.
2. If the plugin is too new for your Grafana version, downgrade the plugin to a compatible version, or upgrade Grafana.
3. If the plugin is too old for your Grafana version, update the plugin to the latest compatible version.
4. Clear the browser cache and reload after you change versions.

Pin or test a plugin version on self-managed Grafana

On self-managed Grafana, you control which plugin version is installed. To install a specific version with grafana-cli:

Bash Copy

grafana-cli plugins install grafana-iot-sitewise-datasource 1.25.2

To pin the version in a container image, set the version in the GF_INSTALL_PLUGINS environment variable:

Bash Copy

GF_INSTALL_PLUGINS=grafana-iot-sitewise-datasource@1.25.2

Test plugin and Grafana upgrades in a non-production instance before you upgrade production. This lets you confirm compatibility without affecting live dashboards.

Grafana Cloud upgrades

In Grafana Cloud, plugins update automatically and you can’t self-service a rollback to a previous plugin version.

Authentication errors

These errors occur when credentials are invalid, missing, or don’t have the required permissions.

“The security token included in the request is invalid”

Symptoms:

• Save & test fails with a security token error.
• Queries return authorization errors.

Possible causes and solutions:

“Access denied” or “not authorized”

Symptoms:

• Queries fail with access denied messages.
• Assets, models, or properties don’t load in drop-down menus.

Solutions:

1. Confirm that the IAM identity has iotsitewise:List*, iotsitewise:Describe*, and iotsitewise:Get* permissions.
2. To use the SQL editor, grant iotsitewise:ExecuteQuery.
3. For cross-account access, verify the assume role Amazon Resource Name and external ID.

Connection errors

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

Connection refused or timeout errors

Symptoms:

• The data source test times out.
• Queries fail with network errors.

Solutions:

1. Verify network connectivity from the Grafana server to the AWS IoT SiteWise endpoints.
2. Check that firewall rules allow outbound HTTPS on port 443.
3. If you set a custom endpoint, verify that the URL is correct and reachable.
4. For Grafana Cloud accessing private resources, configure Private data source connect.

SiteWise Edge errors

These errors occur when you configure a SiteWise Edge gateway connection.

“edge region requires an explicit endpoint”

Symptoms:

• Save & test fails after you select Edge as the Region.

Solution:

Set the Endpoint field to the URL of your SiteWise Edge gateway.

“edge region requires an SSL certificate”

Symptoms:

• Save & test fails for an Edge connection, in any authentication mode.

Solution:

Provide a valid PEM certificate in the SSL Certificate field. An SSL certificate is required for all Edge connections, including the Standard authentication mode. The value begins with -----BEGIN CERTIFICATE-----.

“missing edge auth user” or “missing edge auth password”

Symptoms:

• Save & test fails with a message about a missing Edge authentication user or password.

Solution:

For the Linux and LDAP authentication modes, provide both the Username and Password for the gateway’s local authentication proxy. The Standard mode uses the authentication provider configured above and doesn’t require these fields.

Query errors

These errors occur when you run queries against the data source.

No data or empty results

Symptoms:

• A query runs without error but returns no data.
• Panels show a “No data” message.

Possible causes and solutions:

API throttling or rate limit errors

Symptoms:

• Queries fail intermittently with throttling or “rate exceeded” errors.
• Panels fail to load when a dashboard has many queries.

Solutions:

1. Reduce the dashboard refresh frequency.
2. Increase the aggregate resolution to reduce the number of API calls.
3. Keep the Client cache option enabled to reuse results for relative time ranges.
4. Request a quota increase from AWS.

Field name issues

Panel overrides and transformations can break when the field names in a query result change. The data source builds field names from the names it reads from AWS IoT SiteWise: the value field is typically named after the property, and the series after the asset. The plugin resolves these names in the query’s Region.

Why field names change

Use field overrides safely

Hard-coded field names break when the underlying names change. To make overrides and transformations more resilient:

• Use the Fields with name matching regex override matcher instead of Fields with name, so a partial match still applies when a name changes.
• Match fields by type, such as all numeric fields, when the override doesn’t depend on a specific field.
• Add a Rename by regex or Organize fields transformation to set stable display names before you apply overrides.
• Set the Region explicitly in the query rather than relying on the default Region, so name resolution stays consistent.

Check the default Region

A changed or mismatched default Region is a common cause of field names that appear as “not found” in overrides.

1. In Builder mode, set the query Region explicitly instead of using Default.
2. Verify that the Default Region in the data source configuration matches where your assets are stored.
3. Confirm that the assets and properties you query exist in the selected Region.

Clear stale results from the client cache

If field names look stale after you rename assets or properties, change tags, or switch the Region, clear the cached results:

1. In Builder mode, expand Query options and turn off Client cache.
2. Run the query again to fetch fresh results.
3. Re-enable Client cache if you want to continue reusing results for relative time ranges.

The Builder (SQL) and Code (SQL) modes don’t use the client cache, so you can also run the same query in an SQL mode to bypass cached results.

Property alias display

When you query by property alias, you might expect the panel to show the full alias, such as an OPC-UA path. Instead, the data source shows the asset property name.

Property name takes priority over the alias

The data source builds series and field names from the metadata it reads from AWS IoT SiteWise. When a property resolves to an asset property that has a name, the plugin uses the asset property name for the series and field names, not the full property alias. This behavior is intentional.

As a result:

• A Get property value or Get property value history query names the series after the asset and names the value field after the property.
• The full alias isn’t shown as the field name, even when you query by alias.

If you need the alias to appear in the panel, add a Rename by regex or Organize fields transformation to set the display name you want.

Alias resolution and property data types

Alias resolution can behave differently depending on the property’s data type, such as a boolean property compared with a numeric property. For a property queried by alias, the data source infers the data type from the first returned value when the type isn’t otherwise defined, so the resolved name or type can differ between data types. If a property queried by alias shows an unexpected or inconsistent name:

1. Verify that the property alias is correct and associated with the expected asset property.
2. Where possible, query by asset and property instead of by alias, so the plugin resolves a consistent asset property name.
3. Add a Rename by regex or Organize fields transformation to set a stable display name.

Intermittent “No data” after saving a dashboard during a fallback

Symptoms:

• Stat or time series panels that query by property alias intermittently show “No data”.
• A saved field override or field selection references a raw alias path, but the query currently returns the asset property name.

Cause: The data source caches alias resolution metadata for a short period. If the metadata lookup temporarily fails, the data source falls back to using the raw property alias as the field name. If you save the dashboard while the fallback is active, the saved field name no longer matches the field name the data source returns after resolution recovers.

Solution:

1. Re-select the field in the panel options or field override so it matches the current field name, then save the dashboard again.
2. To confirm a fallback occurred, enable debug logging and look for log entries about the raw property alias fallback. Plugin version 2.6.0 added debug logging for this fallback.

Template variable errors

These errors occur when you use template variables with the data source.

Variables return no values

Solutions:

1. Verify that the data source connection works by testing it in the data source settings.
2. Use a query type that returns variable options: List asset models, List assets, or List associated assets.
3. For the List assets query, verify that the Model ID is set when you use the All filter.
4. Verify that the identity has permission to list the requested resources.

Alert rule errors

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

“input data must be a wide series but got type long”

Symptoms:

• A query returns data in a dashboard panel, but the same query fails in an alert rule with an error such as input data must be a wide series but got type long.

Cause: Alert conditions can only evaluate numeric data. This error occurs when the alert rule query returns string values or table-formatted data that Grafana can’t reduce to a number for the alert condition.

Solution: Build the alert rule query so it returns numeric time series data, such as a numeric asset property with the Time series format. Refer to Query requirements for alerting.

Enable debug logging

To capture detailed error information for troubleshooting:

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

   ini Copy

   [log]
   level = debug

2. Review logs in /var/log/grafana/grafana.log, or your configured log location.

3. Look for AWS IoT SiteWise entries that include request and response details.

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

Get additional help

If you’ve tried the solutions in this document and still encounter issues:

1. Check the Grafana community forums for similar issues.
2. Review the AWS IoT SiteWise data source plugin GitHub issues for known bugs.
3. Consult the AWS IoT SiteWise documentation for service-specific guidance.
4. When you report an issue, include:
   • Your Grafana version and plugin version.
   • Error messages, with sensitive information redacted.
   • Steps to reproduce the issue.
   • Relevant configuration, with credentials redacted.