Troubleshooting tenant onboarding issues

Use this topic for information about the common causes of tenant onboarding failures and the actions required to resume the onboarding process.

To restart tenant onboarding using tctl commands

The tenant onboarding flow can be interrupted because of infrastructure or environment failures. After you fix the infrastructure issues, run the following commands to resume the tenant onboarding flow from the point where it failed:

To get the list of all tenants on a stack, run the following command:
tctl get tenant
To resume the tenant onboarding, run the following command:
tctl resume tenant <tenantid>

Watch the video Tenant Activation Email to know how to resend a tenant activation email using the TCTL utility.

To troubleshoot SMTP related issues

When Simple Mail Transfer Protocol (SMTP) is disabled or incorrectly configured, email notifications and tenant onboarding emails fail to send. This issue typically occurs if the SMTP service is unavailable during deployment or if incorrect SMTP credentials were stored in the configuration.

Issue symptoms

Email notifications are not delivered from the Tenant Management Service (TMS).
The following symptoms may be observed:

No onboarding or password reset emails are received.
SMTP validation warnings appear during deployment.
TMS logs show SMTP connection or authentication failures.

Issue scope

The issue occurs when:

SMTP is disabled (SMTP_ENABLE=no) during deployment.
The SMTP service becomes available later, but TMS continues to use the earlier invalid or empty SMTP configuration.
The smtp-credentials-helm configmap or Secret contains incorrect values.
The base64-encoded smtp-password is invalid.

Resolution

After a working SMTP server becomes available, you can re-enable emails in an existing on-prem deployment by updating the SMTP configuration.

Perform the following steps to enable SMTP on an already installed on-prem environment:

Open /configs/infra.config and update all SMTP-related parameters with valid working SMTP values:

SMTP_ENABLE=yes
SMTP_HOST=
SMTP_PORT=
SMTP_USERNAME=
SMTP_FROM_EMAIL=
SMTP_TLS=false
SMTP_AUTH_DASHBOARD=true
SMTP_AUTH=NONE
OPS_GROUP_EMAIL=
APPROVAL_GROUP_EMAIL=

For more information about the configmap details, refer to Configuration file settings.

Open /commons/certs/secrets.txt and update the working SMTP password:

SMTP_PASSWORD=

For more information about the secret parameters, refer to Preparing for password encryption.

Important

Make sure that all secret values are base64 encoded.

Re-run the Helix ITOM On-Prem Deployment to apply the updated SMTP configuration.

After restarting, verify that SMTP connectivity is successful and email notifications are delivered.