Oracle Cloud Infrastructure Documentation

Troubleshooting

Use troubleshooting information to identify and address common issues that can occur when working with your Internet of Things (IoT) Platform.

Make sure you have the required permissions. An administrator grants access by creating the required policies. For more information, see Prerequisites and Policy Details for the Internet of Things (IoT) Platform.

Update your passwords

You may need to reset your database password when connecting to the database using APEX, or when connecting directly to the database using the Identity domain group.

Cause: If you are using APEX and you need to reset your password

If you configure access to view your IoT data in APEX, then two different users are created, a database user and an APEX Workspace Administrator user. These are two different users with the same user name and the same initial password. You can update the passwords for each user.

Remedy: Update your APEX database password

  1. Only an APEX workspace administrator can change the database user's password. Initially, the APEX workspace administrator uses your APEX database password to log in, and then follows these steps to change the database password.

    In APEX, log in to the IoT domain's Workspace as an administrator, using the following as the workspace name and database user name, with your current APEX database password.
    Note

    Notice the two underscores __WKSP.
    <domain-short-id-from-device-host>__WKSP
  2. Go to SQL Workshop, select SQL Commands.
  3. Confirm the <iot-domain-short-id-from-device-host>__WKSP schema is selected from the top right schema drop-down menu. Notice the schema contains two underscores.
  4. Use this SQL ALTER USER statement and the required REPLACE clause to change your database user's password:
    ALTER USER <workspace-administrator-user-name> IDENTIFIED BY "<new-password>" REPLACE "<old-password>";
  5. Select Run.
  6. Example results showing the password update:
    User altered.

0.24 seconds

Remedy: Update your APEX password

To change your APEX password:
  • As an APEX workspace administrator, you can change the workspace admin password. After logging into APEX as an administrator, select the Set APEX Account Password option. For more information, see Resetting your password in APEX.
  • As an APEX user, when you log in to the APEX application for the first time, you will be prompted to change your APEX password. After your initial log in, you can reset your password on the APEX log in page.
Note

Depending on the system you use, double quotes may be required when your password contains special characters.

Remedy: Reset the APEX workspace password using the API

As an APEX workspace administrator, you can change if the IoT APEX workspace account is locked, as an administrator you can run this ConfigureIotDomainDataAccess operation twice to reset the APEX workspace password. 
POST /20250531/iotDomains/{iotDomainId}/actions/configureDataAccess
{
  "type": "APEX",
  "dbWorkspaceAdminInitialPassword": "<your-apex-initial-password>"
}

Cause: Missing authorization when connecting directly to the database

If you establish a direct connection to the database using the following CLI command, and you don't have authorization to connect directly to the database, then you can create a new database password for the Identity domain group to connect.

For example, when you use the oci iot domain configure-direct-data-access command and the required parameters to configure an IoT domain's authentication to establish a direct database connection and you can not connect. 

oci iot domain configure-direct-data-access --iot-domain-id <iot-domain-OCID> --db-allow-listed-identity-group-names '["<tenancy-OCID:<identity-domain-name>/<identity-group-name>"]'

or if you use this format:

oci iot domain configure-direct-data-access --iot-domain-id <iot-domain-OCID> --db-allow-listed-identity-group-names '["<tenancy-OCID:<identity-group-name>"]'

Remedy: Update the database password for the Identity domain user

Update your IAM Identity domain user's database password. To do that, log in to your IoT tenancy, and complete the following steps:
  1. Open the navigation menu, go to Identity & Management, select domains.
  2. On the domain list page, select the Identity domain that you want to work with and connect to an IoT domain.
  3. Select the User Management tab, select the user you want to update the password for. Select the Database Passwords tab, to update the password delete your current IAM database password and create a new IAM database password.

Digital Twin Models Use DTDL Specifications v3

Cause: Creating a digital twin model results in error

When you create a digital twin model if you get an error, confirm you are using only DTDL v3 specifications that are supported.

Remedy: Use only supported v3 DTDL specifications

When you define the digital twin model all DTDL v3 specifications are supported, except MQTT extensions and writable properties.
  • If a writable property is included in the digital twin model, it must be set to false.
  • Only the content within the component can be annotated as historized, indicating the IoT platform must retain that sensor’s time-series telemetry, see the digital twin model example dtdl-model-specifications.json. For an example, see Creating a Digital Twin Model.

Service Limits Exceeded

Troubleshoot IoT domain or IoT domain group resource service limits per region.

Cause: IoT resources limits per region

Internet of Things (IoT) Platform has limits on the number of resources per region.

If you try to create more than 2 IoT domains or more in an IoT domain group, then you may see the following error. For more information, see create an IoT domain or an IoT domain group.

The following service limits were exceeded: <resource-count>. Request a service limit increase from the service limits page in the console.

Note

Oracle restricts creating up to 2 IoT domains in each IoT domain group. The maximum number of IoT domain groups is 5 and maximum number IoT domains is 10 per region in your tenancy. To create an IoT domain your user must have read access for the associated IoT domain group.

Remedy: Upgrade and increase the limits

See Service Limits to review the limits for IoT resources. If you need to increase the limits, you can request a service limit increase.

Using quotes with OCIDs

In Oracle Cloud Infrastructure (OCI), an OCID (Oracle Cloud Identifier) is a unique ID assigned to each cloud resource. Depending on the specific scenario, when interacting with OCI through the Command Line Interface (CLI), JSON input, or API calls, you may need to quote the OCID so its interpreted as string value. Or you may need to remove quotes if a code editor you are working adds unwanted quotes.

Note

Some applications or code editors may add unwanted quotes to your values, review and remove any unwanted quotes or this can cause an error.

To conform to JSON standards and ensure correct interpretation by OCI services an OCID must be enclosed in double quotes, so that its treated as string value within JSON structures or complex inputs. When passed as direct, simple arguments to CLI commands, explicit quoting is often not required.

  • Not quoting OCIDs in CLI: If an OCID is a direct argument to a CLI command, you do not need to explicitly use quotes unless it's part of a larger string or a complex type that requires quoting.
    This example shows using an OCID is a CLI command without quotes:
    oci iot digital-twin-adapter create --iot-domain-id ocid1.iotdomain.oc1.example-ocid
  • Quoting OCIDs when embedding within JSON strings: If you are passing a complex parameter to a CLI command as a JSON string with an OCID value, then the OCID within the JSON string must be enclosed in double quotes and escaped if necessary. Depending on the tool and operating system you are using, for Windows its required. For more information, see Passing Complex Input in CLI.
  • Quoting OCIDs in JSON objects: All string values within a JSON object must be enclosed in double quotes. If an OCID is a value in a JSON object that you are sending to OCI using an API or in a CLI command, it must be double-quoted:
    { "displayName": "my_resource", "compartmentId": "ocid1.compartment.oc1..<example>" }
  • Quoting OCIDs in API Calls: In request bodies or parameters: When making API calls to OCI, if an OCID is part of the request body as a JSON payload or a query parameter, then it should be treated as a string and enclosed in double quotes within the JSON payload. Or it must be properly encoded as a string for URL parameters. The specific requirements depend on the API endpoint and the data type expected for that parameter.

In Digital Twin Instances using quotes for an external key

External key equals device username: If a digital twin instance is created with quotes embedded in the external key for example: "\"american-auto\"", then the basic authentication username then those quotes become part of the required username and must be sent literally. This often causes shell quoting issues. If you included quotes in your external key name, then your curl request must also include the quotes, or a mismatch occurs and results in a 401 Unauthorized error.

If you use quotes in your digital twin instance external key value, then you must use the quotes when you make an API call. Or you can omit the quotes in your external key value.

To avoid quoting issues, do not use quotes in a digital twin instance's external key value. For example, this shows the --external-key CLI parameter and the corresponding value that does not use quotes:

--external-key 01-23-45-67-89-ab

Best practice: Create digital twin instances with external keys and do not include quotes for example, american-auto Or when you must authenticate with quoted usernames, construct an Authorization: Basic ... header rather than using -u to avoid quoting errors.

In Digital Twin Adapters JSON objects must use quotes

Unquoted expressions are not supported in digital twin adapter inbound routes. For more examples, see Scenarios.

In a digital twin adapter, the inbound-route expressions are not supported as raw values without quotes, for example:

"$.speed": ${(.velocity_kph / 1.609) | floor}
In a digital twin adapter, for the inbound-route values expressions must be embedded as strings using quotes, for example: 
"$.speed": "${(.velocity_kph / 1.609) | floor}"

Troubleshooting IoT Flow Runtimes

Identify and resolve common problems with Flow Runtime lifecycle operations, IAM policies, the Node-RED editor, flow-document updates, network access, and File Storage mounts.

Before troubleshooting a flow, confirm that you can view the Flow Runtime and its work requests, metrics, events, and configured logs.

The Flow Runtime doesn't become active

  1. Open the work request created by the activate operation and review its errors.
  2. Confirm that your IAM policies allow you to update the Flow Runtime and read the referenced IoT domain, subnet, network security groups, log, mount target, and export.
  3. Verify that every referenced resource exists in the expected compartment and region.
  4. Correct the reported configuration problem, activate the runtime again, and wait for the work request to complete.

The Node-RED editor doesn't open or a flow update fails

  1. Confirm that the Flow Runtime lifecycle state is Active.
  2. Confirm that your IAM policies allow access to the IoT domain and Flow Runtime.
  3. Refresh the Flow Runtime details page and select Open Flow Runtime editor again.
  4. Validate the Node-RED flow before selecting Deploy. Correct any node configuration errors reported by the editor.
  5. If Deploy fails in the editor, review the configured log and retrieve the current flows document to compare it with the flow you intended to use.
  6. If the CLI or API update fails, validate that the input is a complete JSON flows document. For the CLI, use the --flows-document parameter and prefix a file path with file://. See Updating Flows for an IoT Flow Runtime. The update operation is synchronous and doesn't create a work request.

A flow can't connect to an external endpoint

  1. Review the runtime's network configuration and confirm that it uses the intended subnet and network security groups.
  2. Confirm that the subnet route table provides a route to the endpoint. For outbound internet access from a private subnet, verify the NAT gateway and routing configuration.
  3. Confirm that security lists and network security groups allow the required outbound protocol and port and any required return traffic.
  4. Verify the endpoint host name, port, TLS configuration, and authentication values in the Node-RED node.
  5. For MQTT, confirm that each Flow Runtime uses a unique client ID. When using shared subscriptions, use the same shared subscription topic on each runtime and a different client ID on each runtime.
  6. Select Deploy for the corrected flow and review the configured log and Flow Runtime metrics.

A File Storage mount isn't available to a flow

  1. Review the runtime's File Storage mount configuration.
  2. Confirm that the mount target and export OCIDs are correct. The configured mount path must be relative, without a leading or trailing slash or path traversal segments. For example, history is available to the Flow Runtime at /mnt/history.
  3. Confirm that the File Storage export's Ports option is set to Privileged.
  4. Confirm that the mount target NSG permits the required File Storage traffic. If the mount target doesn't use an NSG, confirm that its subnet security list has stateful ingress rules from the Flow Runtime subnet CIDR for TCP and UDP port 111 and ports 2048-2051.
  5. When updating the runtime, provide the complete replacement network configuration, including the subnet, network security groups, and all File Storage mounts that must remain attached.
  6. Wait for the update work request to complete, confirm that the file is visible and readable at the mounted path, and then run the flow again.

A flow doesn't produce IoT data

  1. Confirm that the Flow Runtime is active and that the Node-RED editor reports a successful deployment.
  2. Verify that the source is sending messages to the host, port, and topic configured in the input node.
  3. Use Node-RED debug nodes and the configured runtime log to inspect the message before and after each transformation.
  4. Confirm that the output node uses the correct IoT device host, device credential, and topic expected by the digital twin adapter.
  5. If raw data arrives but normalized data is missing, verify the adapter route condition, target mapping, payload mapping, and digital twin instance association.
  6. Review the target digital twin instance's data and the Flow Runtime metrics for processing or delivery failures.

A dequeue node reports an invalid object type or unexpected payload

  1. Choose the queue that matches the flow. For the monitoring scenario, use <domain-short-id>__IOT.NORMALIZED_DATA.
  2. For NORMALIZED_DATA, select a JSON payload and don't specify an ADT object type. A normalized record contains digitalTwinInstanceId, contentPath, value, and timeObserved.
  3. For a flow that intentionally consumes raw input instead, use queue <domain-short-id>__IOT.RAW_DATA_IN and object type <domain-short-id>__IOT.RAW_DATA_IN_TYPE. Don't use the raw object type with the normalized queue.
  4. Enable external authentication and verify that the proxy user is <domain-short-id>_<flow-runtime-short-id>__FR.
  5. Verify that the subscriber exists and that the Dequeue node uses the intended subscriber name.
  6. Select Deploy, publish a test IoT event, and temporarily connect a Debug node to inspect the actual queue payload and field casing.

A shared MQTT subscription produces duplicate messages or disconnects

  1. Configure every participating Flow Runtime with the same shared topic, such as $share/fr-guide/source/+/+.
  2. Give every runtime a unique MQTT client ID. Reusing a client ID can cause one active runtime to disconnect another.
  3. Use MQTT 5.0 and confirm that the broker supports shared subscriptions.
  4. Publish to ordinary topics such as source/hvacs/fr-guide-hvac-01. Don't publish to the $share subscription topic.
  5. Remove any independent source/+/+ subscriptions that would intentionally process the same messages outside the shared group.

Flow Runtime policy troubleshooting

Creating a Flow Runtime with a log group OCID fails, or an OCI node reports NotAuthorizedOrNotFound, 401, or 403.

  1. For an OCI node, confirm that the Flow Runtime compartment and resource type match the dynamic group rule. A new or moved runtime might not match the intended rule.
  2. For an OCI node, confirm that the resource principal policy subject uses the correct dynamic group and identity domain.
  3. For an OCI node, confirm that the resource principal policy is created in the compartment containing the target resource or an appropriate parent compartment.
  4. For an existing log, confirm that the creation-time Logging policies grant read log-groups and use log-content. If you selected only a log group for automatic log creation, confirm that the policies grant manage log-groups and use log-content. Verify that the policies apply to the compartment containing the log group and that the configured log group and log OCIDs are correct.
  5. For an OCI node, identify the operation that failed and compare it with the least-privilege example for Object Storage, Notifications, or IoT nodes.
  6. Confirm that the target OCID, compartment, bucket name, topic, or database is the resource named by the resource principal policy.
  7. After changing a dynamic group or policy, wait for IAM changes to take effect, deploy or retry the operation, and review the Flow Runtime log.
  8. If the policy matches the documented requirement and access is still denied, collect the work request error, request ID, runtime OCID, target resource OCID, and policy statements before contacting Oracle Support.