Troubleshooting¶

Application Won't Start¶

503 Service Unavailable on First Launch¶

This is expected. On first launch, the application applies database migrations and seeds default settings. This can take a minute or more. The Retry-After header indicates when to try again.

Database Connection Errors¶

Verify your connection string is correct and the SQL Server is accessible from the application host. For Azure deployments, ensure the App Service has network access to the Azure SQL Database (check firewall rules).

Sync Issues¶

Entity Shows "Failed" Status¶

Click the entity name on the Dashboard to see the error details. Common causes:

API throttling — The Autotask API has rate limits. Autotask Mirror handles throttling automatically with retry logic, but sustained heavy usage may cause temporary failures. Consider increasing the sync interval for less critical entities.
API credentials expired — Verify your API credentials on the API Settings page. Changes take effect within 60 seconds.
Network timeout — Large entities with thousands of records may time out on slow connections. The job will automatically retry.

Sync is Running But No Data Appears¶

Verify API credentials are correct on the API Settings page
Check that the entity is Enabled on the Dashboard
Look at the Records column — if it shows 0, the Autotask API returned no records for that entity type
Check the Hangfire Dashboard (/hangfire) for detailed job logs

All Entities Show "Interrupted" Status¶

This typically happens after an unexpected application shutdown (crash, deployment, or host restart). The application automatically clears stale "Running" statuses on startup and marks them as "Interrupted." The next scheduled run will proceed normally.

Authentication Issues¶

This banner appears when the Authentication:Authority setting is empty. See the Authentication guide to configure your identity provider.

This usually indicates a misconfigured redirect URI. Verify that:

The redirect URI in your identity provider matches your application URL + /signin-oidc
The CallbackPath in your configuration matches what's registered with the provider (default: /signin-oidc)
Your identity provider's application is configured for Web platform (not SPA or native)

Certificate Errors with On-Premises Identity Provider¶

If your ADFS or Keycloak server uses a self-signed TLS certificate, set DangerousAcceptAnyTlsCertificate to true in the Authentication configuration. See Authentication — ADFS.

Performance¶

Sync Jobs Are Slow¶

Increase worker count — More workers allow more entities to sync in parallel. See Preferences.
Use incremental sync — Entities that support incremental mode only fetch changed records, which is significantly faster than full sync.
Stagger schedules — Avoid setting many entities to the same interval and start time. The default configuration automatically staggers start times.

Database Size Growing Large¶

The mirror database grows proportionally to the amount of data in your Autotask instance. For very large instances:

Disable entities you don't need for reporting
Consider disabling the Document module if not needed (document attachments can be large)
Monitor database size in the Azure Portal and scale the database tier as needed

Azure Marketplace Specific¶

Managed Identity Errors¶

The Marketplace deployment uses a managed identity for database access. If you see authentication errors connecting to SQL:

Verify the App Service managed identity is enabled in the Azure Portal
Confirm the managed identity has been granted access to the SQL database
Check that the connection string uses Authentication=Active Directory Default