Troubleshooting

The following troubleshooting tips might help you to resolve issues with this Micro-Integration. If problems persist, contact Solace.

We strongly recommend configuring a Dead Message Queue (DMQ) on the event broker queue before deploying the Micro-Integration. When a message cannot be delivered to Databricks, the Micro-Integration NACKs it and the event broker sends it to the DMQ so it can be inspected and reprocessed. Without a DMQ, NACKed messages are permanently lost.

Authentication Errors

If the Micro-Integration logs an authentication error or fails to connect:

  • Verify that the Client ID and Client Secret are correct. You can check them on the service principal's Configurations and Secrets tabs in the Databricks workspace.

  • Check that the service principal's client secret has not expired. Databricks client secrets have a configurable lifetime. If the secret has expired, generate a new one and update clientSecret in your application.yml.

  • Confirm that the service principal has not been deleted or disabled in the Databricks workspace.

  • Ensure that the service principal has the required privileges on the target Unity Catalog table. For more information, see Setting Up a Service Principal.

Table Not Found Errors

If the Micro-Integration logs errors indicating that the target table cannot be found:

  • Verify that the catalog, schema, and table values in your application.yml match the fully-qualified name of an existing Delta table.

  • Confirm that the target table exists in the Databricks workspace. The Micro-Integration does not create tables automatically.

  • Check that the service principal has USE CATALOG, USE SCHEMA, MODIFY, and SELECT privileges on the target table. For more information, see Setting Up a Service Principal.

Schema Mismatch or Unknown Column Errors

If the Micro-Integration logs errors about unrecognized or unexpected columns:

  • Check that the message payload does not contain fields absent from the Delta table schema. Add missing columns to the table before sending records that include those fields. The Micro-Integration does not update table schema automatically.

  • Ensure that all column names use only ASCII letters, digits, and underscores.

gRPC Connection Failures

If the Micro-Integration logs gRPC connection errors or transport-level failures:

  • Check that no proxy or middleware is placed between the Micro-Integration and Databricks. Proxies that strip HTTP/2 headers will break the gRPC connection.

  • Verify that your network allows outbound TLS 1.2 or higher connections to the Zerobus server endpoint.

  • Confirm that both the Databricks workspace and the target table are deployed in a region that supports Zerobus Ingest. For supported regions, see AWS feature region support or Azure feature region support. Both must be in the same supported region.

Micro-Integration Stops Working After Running Correctly

If a previously working Micro-Integration suddenly stops:

  • Check that the service principal's client secret has not expired. Databricks client secrets have a configurable lifetime. If expired, generate a new secret and update clientSecret in your application.yml.

  • Verify that the service principal still exists and is active in the Databricks workspace.

  • Ensure that the service principal still has the required privileges on the target table. A workspace admin can revoke privilege grants.