Troubleshooting Micro-Integrations in Solace Cloud

If you are unable to deploy your Micro-Integration or you encounter other issues, use the following guidance to diagnose and resolve the problem.

• Viewing the Error Logs—Review the error logs to help identify specific issues with your Micro-Integration.

• Common Issues and Solutions—Resolve frequently encountered problems including deployment failures, connection issues, authentication errors, and performance problems.

• Best Practices—Follow the recommended practices to prevent issues and ensure the smooth operation of your Micro-Integration.

If problems persist, contact Solace.

Viewing the Error Logs

You can view the error logs for a Micro-Integration. The logs are useful for helping to understand issues that occurred while deploying your Micro-Integration and can provide you with information to resolve the underlying problems. Only the last ten error logs are available.

To view the error logs for a Micro-Integration, perform the following steps:

1. Log in to the Solace Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Logging In to the Solace Cloud Console.

2. On the navigation bar, select Micro-Integrations.

3. On the Micro-Integrations page, click the name of the Micro-Integration you want to view the error logs for.

4. On the Micro-Integrations page, click the ellipsis and select View Logs.

   

   The View Logs option is available only if the Micro-Integration has been deployed at least once.

5. From the list of logs on the Recent Error Logs page, select the error log to view its details.

Common Issues and Solutions

The following sections describe common issues you may encounter when working with Micro-Integrations and how to resolve them.

Unable to Deploy Status

If your Micro-Integration shows an Unable to Deploy status, this indicates configuration problems that prevent deployment. To resolve this issue:

• Check the error logs as described in Viewing the Error Logs to identify the specific configuration issue.

• Verify that all required fields are correctly configured in both the Source Connection and Target Connection steps. For more information, see Event Broker Service Configuration and Vendor-Specific Configuration.

• Ensure that at least one Flow is configured for the Micro-Integration.

• Verify that the event broker service you selected is running and accessible.

• Check whether you are having Environment-Related Issues.

Connection Failures

Connection failures can occur when the Micro-Integration cannot establish a connection to the event broker service or external system. To troubleshoot connection issues:

• Verify that the host URI and port are correct. For event broker service connections, ensure you are using the correct protocol (tcp:// or tcps://) and SMF port.

• Check that the Message VPN name is correct and that the VPN is enabled on the event broker service.

• Verify that your authentication credentials (username and password, client certificate, or OAuth 2.0 token) are valid and have not expired.

• If you're using SSL/TLS connections, ensure that the certificate validation settings are correctly configured. For more information, see Trust Store Parameters.

• For external system connections, verify that network connectivity exists and that any required firewall rules or security groups allow traffic from the Micro-Integration.

Authentication Errors

Authentication errors prevent the Micro-Integration from authenticating with the event broker service or external system. To resolve authentication issues:

• Verify that the authentication scheme selected matches the configuration on the event broker service or external system.

• For basic authentication, confirm that the client username and password are correct and that the user account is enabled.

• For client certificate authentication, ensure that:

  • the key store file is in the correct format (JKS or PKCS12)

  • the key store password and private key password are correct

  • the client private key alias matches the alias in the key store

  • the certificate has not expired

• For OAuth 2.0 authentication, verify that the token URI, client ID, client secret, and scopes are correctly configured.

Message Flow Issues

If your Micro-Integration is deployed and running but messages are not flowing as expected:

• Verify that the source queue or topic endpoint exists on the event broker service and contains messages.

• Check that the destination queue or topic is correctly configured and accessible.

• Review the Total Errors metric on the Micro-Integration details page to identify if errors are occurring during message processing.

• Verify that any message selectors configured on the Flow are not filtering out all messages.

• Check that header and payload mappings are correctly configured. For more information, see Mapping Headers and Payloads.

Performance Issues

If your Micro-Integration is processing messages slower than expected:

• Monitor the Messages Per Second and Bytes Per Second metrics on the Micro-Integration details page to understand current throughput.

• Check if the external system is experiencing performance issues or throttling requests.

• Review the complexity of your header and payload mappings, as complex transformations can impact performance.

• Verify that the event broker service has sufficient resources and is not experiencing performance issues.

• If you cannot resolve the slow performance of your Micro-Integration, contact Solace.

Deployment Stuck in Deploying State

If your Micro-Integration remains in the Deploying state for an extended period:

• Wait a few minutes; deployment typically takes several minutes to complete.

• If the Micro-Integration remains in the Deploying state for more than 10 minutes, try undeploying and redeploying it. For more information, see Undeploying a Micro-Integration and Deploying a Micro-Integration.

• If the issue persists, contact Solace.

Event Broker Service Deleted or Unavailable

If you delete an event broker service that is being used by a Micro-Integration, the Micro-Integration will have its event broker connection details removed and will not be deployable. To resolve this:

• Edit the Micro-Integration and select a new event broker service. For more information, see Editing a Micro-Integration.

Environment-Related Issues

If you are using multiple environments and experiencing issues:

• Verify that you have selected the correct environment where your Micro-Integration and event broker service are located. For more information, see Selecting Environments.

• Ensure that the Micro-Integration and event broker service are in the same environment, as cross-environment connections are not supported.

• Note that you cannot clone a Micro-Integration from one environment to another. If you need to replicate a Micro-Integration in a different environment, you must manually re-create it.

Best Practices

Follow these best practices to minimize issues with your Micro-Integrations:

• Test your Micro-Integration configuration in a non-production environment before deploying to production. For more information, see Creating and Managing Environments.

• Use descriptive names for your Micro-Integrations and Flows to make them easier to identify and manage.

• Regularly monitor the metrics on the Micro-Integration details page to ensure your Micro-Integration is performing as expected. For more information, see Viewing Micro-Integration Metrics.

• When issues occur, promptly review the error logs to identify and resolve problems quickly.

• Ensure that queues and topic endpoints are created on the event broker service before deploying the Micro-Integration.

• When you use AI-generated mappings, always manually verify the mappings and transformations to ensure they are correct.

• Keep your authentication credentials secure and rotate them regularly according to your organization's security policies.