Document generation failures

Overview

Document generation failures occur when Azure Documenter cannot complete generating a document from a saved configuration. Failures can affect both on-demand generation triggered from the document configurations list and scheduled generation runs.

Business value

Quickly diagnosing document generation failures reduces the time stakeholders wait for reports and prevents governance or compliance processes from being interrupted by silent failures. Most generation issues resolve once the underlying configuration, permission, or publish setting is corrected.

How it works

When you generate a document, Azure Documenter retrieves Azure resource and cost data using the Service principal and subscription scope defined in the configuration, processes the data for the selected document type, and publishes the output to the configured destination — Azure Storage account or Document360. A failure at any of these stages prevents the document from being generated or delivered.

Scheduled generation failures are not surfaced in the product unless email notifications are enabled in the configuration's Notifications step. Enable notifications on every scheduled configuration so that failures are reported immediately to the team responsible for the report.

Troubleshooting

1. Generate document option is unavailable in the Actions menu
   Cause: The signed-in user's role has only Read access to the Documentation feature, or does not have a built-in Account owner, Owner, or Contributor role.
   Fix: Ask an Account owner or Owner to set Manage access to the Documentation feature for the user's custom role, or assign a built-in role with full access. See Managing document configurations{target=_blank} for the required permissions table.

2. Generation completes but the document is empty or missing sections
   Cause: The Service principal in the configuration's subscription scope does not have Reader access to one or more of the configured subscriptions. Azure Documenter generates with the data it can access and silently omits the rest.
   Fix: In the Azure portal, verify that the Service principal has Reader access on every subscription included in the configuration. Then generate again. See Service principal permission errors{target=_blank} for a full diagnostic guide.

3. Scheduled generation stops running without notification
   Cause: The client secret on the Service principal has expired, or the Service principal has been deleted or disabled in Microsoft Entra ID. Generation fails silently on every scheduled run until the issue is resolved.
   Fix: Open Service principals in Azure Documenter and check the status and expiry date of the Service principal used in the configuration. Rotate the client secret and update the expiration date if expired, or register a replacement Service principal if the original has been removed. See Service principal permission errors{target=_blank}.

4. Generation fails to publish to Azure Storage account
   Cause: The Azure Storage account configured as the publish destination is no longer accessible — the storage account may have been deleted, moved, or had its access keys rotated without updating Azure Documenter.
   Fix: Open the configuration for editing, navigate to the Publish settings step, and verify the Azure Storage account destination. Update or reconfigure the storage account connection as needed. See Managing storage accounts{target=_blank}.

5. Generation takes an unexpectedly long time and appears stuck
   Cause: The configuration includes a large number of subscriptions, or the selected document type processes extensive resource data (such as Resource details or Resource auditing). Generation time scales with scope and document type complexity.
   Fix: Allow sufficient time for generation to complete — large environments can take several minutes. If generation does not complete after an extended period, verify that the Service principal's access to all configured subscriptions is intact, then retry. To reduce generation time, consider narrowing the subscription scope or splitting large-scope configurations into smaller ones.

Related articles

• Managing document configurations{target=_blank}
• On-demand document generation{target=_blank}
• Service principal permission errors{target=_blank}
• Service principal setup{target=_blank}