Developer Tier APIM Instance Stuck in "Scheduled Maintenance: Started" Status

Hello Lily,

Welcome to the Microsoft Q&A and thank you for posting your questions here.

I understand that your Developer Tier APIM Instance Stuck in "Scheduled Maintenance: Started" Status.

The issue is that the APIM instance is stuck in an Azure-controlled service update/maintenance state. Azure applies APIM service updates automatically through phased rollout, and customers cannot force exactly when an instance receives or completes the update. - https://learn.microsoft.com/en-us/azure/api-management/configure-service-update-settings

What you can do without waiting on backend intervention is to recover the service on a replacement APIM instance, then redirect traffic. For testing, the replacement should not remain on Developer tier if availability matters, because Developer tier is for non-production and does not provide SLA. Use Basic v2, Standard v2, Standard, or Premium, depending on the required features and budget. - https://learn.microsoft.com/en-us/azure/api-management/api-management-features, https://azure.microsoft.com/en-us/pricing/details/api-management/

The best practice is to:

• Confirm the current APIM resource is stuck in maintenance using Resource Health and Activity Log.
• Stop troubleshooting API policies, backend services, keys, or code.
• Create a replacement APIM instance, preferably on an SLA-backed tier.
• Restore from a valid APIM backup if available.
• If no backup exists, redeploy APIs, products, policies, named values, subscriptions, and developer portal configuration from IaC/source control/OpenAPI.
• Reapply custom domains and TLS certificates.
• Redirect DNS/CNAME to the new APIM gateway.
• Keep the original instance only for evidence if Microsoft Support/Product Group root-cause confirmation is required.

After the replacement gateway is deployed and traffic is redirected, customer testing can continue without waiting for the stuck Developer-tier maintenance operation to clear. APIM backup and restore is the documented disaster recovery method for reconstituting an API Management service, and Microsoft notes that custom hostname configuration must be handled separately on the target service. - https://learn.microsoft.com/en-us/azure/api-management/api-management-howto-disaster-recovery-backup-restore, https://learn.microsoft.com/en-us/rest/api/apimanagement/api-management-service/restore?view=rest-apimanagement-2024-05-01. Use the associated resource links for more reading and steps

I hope this is helpful. Please! Do not hesitate to let me know if you have any other questions, steps or clarifications.

Please do not close the thread by upvoting and accepting the answer if any part of it is helpful.

Hi @Lily ,

Thanks for reaching out to Microsoft Q&A.

Your instance is very likely caught in a known Azure-side platform issue, not a misconfiguration on your side and for the Developer tier the correct path is to let the platform recovery complete (or have it cleared from the backend), rather than deleting/recreating.

A Developer-tier APIM instance is a single-unit service with no SLA, so during an Azure platform update it takes the gateway fully offline until the maintenance operation flips from "Started" to "Succeeded." Normally that's minutes. When it stays in "Scheduled Maintenance: Started" for an unusually long time with no gateway traffic, it means the upgrade did not complete successfully on your unit the service failed to bootstrap back up after the update.

This class of issue has recently affected Developer SKU instances across multiple regions due to a regression in a platform upgrade build, where an internal cache (Redis) failed to start during bootstrap, causing the upgrade to time out and the gateway to stay down. In cases like this the fix is on the platform side (pause the rollout / roll back to the last known-good build), after which affected instances recover.

1. Check the Activity log on the instance (portal → your APIM → Activity log) and locate the "Scheduled maintenance" event. This tells you whether the operation is still running or has failed and gives you a timestamp to reference.
2. Run "Diagnose and solve problems" on the instance it has built-in availability/gateway detectors that often surface an in-progress or failed platform operation.
3. Give the platform recovery time. Peer reports of Developer SKU instances stuck after an Azure-initiated reboot/upgrade have recovered on their own once the backend completed, and similar "stuck" locks have auto-released after a few hours. If this is the known upgrade regression, recovery follows the platform rollback.
4. Please avoid deleting/recreating or scaling as a first move. A force-delete or scale operation on an instance that's mid-recovery can leave it in a worse locked/transitioning state. Keep that as a last resort only.

If it's still stuck after several hours, this needs backend investigation/cleanup by Microsoft the Developer tier can't be force-completed from the portal or CLI while it's transitioning. I reached out to you over private message, please share below details over private message

• your resource ID and region (West US 2),
• the exact timestamp and status of the "Scheduled maintenance" event from the Activity log

We will investigate further and update you.

Hope this helps!

If the resolution was helpful, kindly take a moment to click on and click on Yes for was this answer helpful. And, if you have any further query do let us know.