Troubleshoot Connector, instance, item, and mapping errors
Identify Edge Portal resource errors, understand what they mean, and follow verified steps to correct Connector, instance, item, and mapping problems.
Use this guide to identify and troubleshoot errors shown for Connectors, instances, items, and mappings in the Edge Portal. It covers status badges, runtime errors, configuration validation, failed portal actions, item-tag errors, and event history.
The exact runtime message depends on the Connector and connected system. Use the displayed message as the starting point, then check the Connector documentation and logs when it is protocol-specific.
Understand where an error starts
| Resource | What it controls | What to check first |
|---|---|---|
| Connector | The communication driver | Installation, enabled state, license, interface, and repository access |
| Instance | A connection to a device, service, API, or database | Enabled state, address, credentials, parameters, and network access |
| Item | A value or data point | Address, read and write mode, tags, templates, processing, and license capacity |
| Mapping | Data transfer from a sender to a receiver | Endpoints, items, triggers, templates, and receiver access |
If several items or mappings fail at the same time, troubleshoot the Connector and instance first.
Use error indicators and Events
An instance is shown as Online only when it is available and has no last error. Otherwise it is shown as Offline. Open it to read the complete message.
An instance can show Active warnings for item and mapping errors. Open Events to review detected, changed, dismissed, and resolved conditions. Dismissing or muting a notification does not correct its cause.
Follow a consistent troubleshooting process
- Open the affected resource and copy the exact error.
- Open Events to see when it started and whether details changed.
- Check the parent resource.
- Correct the relevant connection or configuration.
- Save and wait for the status to refresh.
- If it remains, match the resource and event time with the system logs.
Use Tools > Ping to test whether the gateway can reach an IP address or hostname.
Troubleshoot Connector errors
| Message or status | What to do |
|---|---|
| License required | Install or activate the required license. |
| Invalid interface | Install a compatible Connector update or package. |
| Failed to load installed connectors | Refresh the page and restore the gateway connection if required. |
| Could not load available connectors. Installed connectors are still shown. | Check internet and DNS access. Installed Connectors and manual installation remain available. |
| No downloadable package was found for this connector. | Use a compatible local package or obtain one for the gateway architecture. |
| A Connector action fails | Read the returned message, refresh the list, and retry the Connector individually. |
Troubleshoot instance errors
| Message or state | What to do |
|---|---|
|
Instance not found The selected instance does not exist or is no longer available. |
Return to the Instances page and refresh it. The instance may have been deleted or become unavailable since the page was opened. |
| Offline with a last error | Use the displayed error to identify and correct the rejected or unreachable setting. |
| Offline without a last error | Confirm that the Connector and instance are enabled, then verify network access. |
| The selected Connector must be installed | Install the Connector and reopen the instance form. |
| Name is required. | Enter an instance name. |
| Connector metadata or setup cannot load | Retry. Verify that the Connector is installed and compatible, then check the logs. |
| An instance create, update, or delete fails | Read the returned gateway message, correct the value or dependency, refresh, and retry. |
Troubleshoot item errors
| Message or state | What to do |
|---|---|
| Item error | Verify the item address and Connector-specific parameters, and confirm that the instance is online. |
| Input template error | Correct the template expression and variables. |
| Post-processing error | Correct the expression and check the next processed value. |
| Inactive: license capacity exceeded. | Reduce the active item count or update the license. |
| This item is read only. | Use a writable item or correct its access configuration where supported. |
| A write, create, update, or delete action fails | Check the instance, item access, required fields, and returned gateway message before retrying. |
| Failed to load reserved tags., Failed to load tags., or Failed to load item tags. | Refresh the item and check the gateway connection. Retry after the item and tag catalogue have loaded. |
| Failed to save item tags. | Confirm that the item still exists and no system tag is assigned to another item, then retry. |
| Failed to update tag. or Failed to delete tag. | Reload the tags and retry. Remember that renaming or deleting a custom tag affects every item that uses it. |
| Tag names cannot be empty. | Enter a tag name. |
| Custom tags may be 1-64 characters and use letters, numbers, spaces, dots, underscores, or hyphens. | Use a valid name that starts with a letter or number. |
See Create and edit items for item configuration and Manage item tags for tag rules and actions.
Troubleshoot mapping errors
| Message or state | What to do |
|---|---|
| Receiver item is read only | Select a writable receiver item. |
| A required sender, receiver, or sender item is missing | Select the missing mapping endpoint. |
| A time-mapping interval is missing or invalid | Enter a positive whole-number interval. |
| Group name is required when multiple sender items are selected. | Enter a group name. |
| A selected instance or item cannot be resolved | Refresh the form and reselect endpoints that still exist. |
| Mapping options cannot load, or save or delete fails | Refresh the page, verify all dependencies, read the returned message, and retry. |
Confirm that the problem is resolved
- Wait for the resource to refresh.
- Confirm that the active error or warning is gone.
- Open Events and confirm that the condition is Resolved.
- For an item, confirm a new value or timestamp.
- For a mapping, confirm that data reaches the receiver.
Collect information for support
- Resource name and identifier
- Complete error text
- Detected time and detail changes
- Relevant log entries
- System, UI, API, and Connector versions
- Relevant network or Ping results