Troubleshooting installations

In this section, you will see some common problems when installing Umbraco Engage and how to solve them.

Boot failure after initial installation

Description

After installing Umbraco Engage and booting for the first time, an SQL exception might be thrown. This happens when Umbraco Engage fails to run the necessary migrations on startup, and the Umbraco Engage tables are not created.

The most common reasons for this are:

• Database connectivity issues.

• Incompatible SQL Server version or edition (columnstore index support required).

• No columnstore index support on Azure SQL tiers lower than S3 (S0, S1, S2).

Exception

SqlException: Invalid object name 'umbracoEngageAbTestingAbTest'.
Umbraco.Engage.Data.AbTesting.DbAbTestRepository.Query(Expression<Func<DbAbTest, bool>> whereExpression) in DbAbTestRepository.cs
Umbraco.Engage.Data.AbTesting.DbAbTestRepository.GetAll() in DbAbTestRepository.cs
Umbraco.Engage.Infrastructure.AbTesting.Repositories.AbTestRepository.GetAll() in AbTestRepository.cs
Umbraco.Engage.Infrastructure.AbTesting.Services.CachedAbTestRepository.RefreshCache() in CachedAbTestRepository.cs
Umbraco.Engage.Infrastructure.AbTesting.Services.CachedAbTestRepository.Handle(MigrationsCompletedEvent event) in CachedAbTestRepository.cs
Umbraco.Engage.Infrastructure.Events.SystemEventService.Raise<T>(T event) in SystemEventService.cs
Umbraco.Engage.Web.Migrations.UmsMigrationsComponent.Initialize() in UmsMigrationsComponent.cs
Umbraco.Cms.Core.Composing.ComponentCollection.Initialize()
Umbraco.Cms.Infrastructure.Runtime.CoreRuntime.StartAsync(CancellationToken cancellationToken, bool isRestarting)
Umbraco.Cms.Infrastructure.Runtime.CoreRuntime.StartAsync(CancellationToken cancellationToken)
Umbraco.Extensions.WebApplicationExtensions.BootUmbracoAsync(WebApplication app)
Program.<Main>$(string[] args) in Program.cs
await app.BootUmbracoAsync();

Steps to resolve

When having database connectivity issues

1. Remove the row with the Umbraco.Core.Upgrader.State+Umbraco.Engage key from the umbracoKeyValue table in the database if it exists.

2. Remove all existing umbracoEngage* tables from the database if they exist.

3. Restart the site.

When running on Azure SQL tier lower than S3

When running Azure SQL on lower tiers and querying columnstore indexes, performance may decrease. Depending on the amount of data being processed, this can also lead to timeouts. This configuration is not recommended for production environments.

Azure SQL lower than S3 doesn't support creating columnstore indexes. To work around this follow these steps:

1. Scale your Azure SQL environment to S3.

2. Restart the site.

3. Scale back to your initial Azure SQL tier.

The columnstore indexes are created and can be used in a lower tier.

When running on an incompatible SQL Server version or edition

SQL Server 2014 or higher is required. Columnstore index support varies by SQL Server version and edition. If you encounter issues, consider upgrading to a newer SQL Server version or using Enterprise Edition.

See System Requirements for the full list of supported database configurations.