Known Issues & Limitations

This document tracks known bugs and limitations in the provider, particularly those related to Microsoft Graph API issues and other external dependencies outside of the provider’s direct control.

How to Report Issues

If you encounter a new issue:

Search Existing Issues

Check this document and GitHub Issues to avoid duplicates

Verify Reproducibility

Confirm the issue is reproducible in your environment and not environment-specific

Report New Issues

Use the GitHub Issue Template and include all required information

Include Details

Provide:

Provider version
Terraform version
Resource name
Reproduction steps
Error messages
Environment details (cloud, OS)

Issue Tracking Template

When documenting issues, use this template for consistency:

### [BUG-XXX] Brief Issue Title

**Bug ID:** BUG-XXX
**Resource:** `resource_name_here`
**Provider Version:** vX.X.X (first affected version)
**Date Reported:** YYYY-MM-DD
**Last Verified:** YYYY-MM-DD
**Impact Level:** Critical/High/Medium/Low

#### Affected API Endpoints
- `/path/to/graph/endpoint`
- `/another/affected/endpoint`

#### Expected Behavior
Description of what should happen according to documentation.

#### Observed Behavior
Description of what actually happens, including error messages.

#### Reproduction Steps
1. Step one
2. Step two
3. Step three

#### Environment Details
- **Affected Clouds:** Public/GCC/GCC High/DoD/China/All
- **Terraform Version:** vX.X.X
- **Provider Version:** vX.X.X
- **Operating System:** Windows/macOS/Linux

#### Status
- **Current Status:** Open/Investigating/Microsoft Acknowledged/Fixed/Workaround Available
- **Microsoft Status:** Not Reported/Reported/Acknowledged/In Progress/Fixed/Won't Fix
- **Upstream Links:**
  - Microsoft Graph Known Issues: [link if applicable]
  - GitHub Issues: [link to related issues]

#### Workarounds
Description of available workarounds.

#### Additional Notes
Any other relevant information.

Current Known Issues

Microsoft Graph API Limitations

[GRAPH-001] Eventual Consistency with Assignment Changes

Impact Level: MediumAffected Resources:

microsoft365_graph_beta_device_management_windows_update_ring
microsoft365_graph_beta_device_management_* (assignment-related resources)

Issue: Assignment filter changes are accepted by the API but may not be immediately visible in read operations due to Microsoft Graph eventual consistency. Devices may continue to receive old assignment targeting for up to 24 hours.Affected API Endpoints:

/deviceManagement/deviceConfigurations/{id}/assign
/deviceManagement/deviceConfigurations/{id}?$expand=assignments

Status: Microsoft Acknowledged - Known limitation of Graph APIWorkarounds:

Wait Period: Allow 15-30 minutes after assignment changes before expecting full consistency
Retry Logic: Implement retry logic in deployment pipelines when checking assignment state
Manual Verification: Verify assignment changes in Microsoft Endpoint Manager console

Additional Notes: This is a known limitation of Microsoft Graph’s eventual consistency model, not a provider bug. The provider correctly sends API requests, but Microsoft’s backend systems require time to propagate changes.

[GRAPH-002] Throttling and Rate Limits

Impact Level: MediumIssue: Microsoft Graph API implements throttling to protect service health. Large-scale Terraform deployments may encounter HTTP 429 (Too Many Requests) errors.Affected Operations:

Bulk resource creation
Large terraform apply operations
Concurrent operations across multiple resources

Status: Microsoft Documented - Working as designedWorkarounds:

Provider Retry Logic: The provider automatically retries with exponential backoff
Spread Operations: Break large deployments into smaller batches
Sequential Execution: Use -parallelism=1 flag to reduce concurrent API calls:
```
terraform apply -parallelism=1
```
Wait Between Runs: Add delays between successive terraform apply operations

Rate Limit Details:

Per-user limits: ~2,000 requests per 5 minutes
Per-app limits: ~10,000 requests per 10 minutes
Limits vary by endpoint and tenant

References:

Microsoft Graph throttling guidance

[GRAPH-003] Beta API Stability

Impact Level: Low to MediumAffected Resources:

All resources using microsoft365_graph_beta_* prefix

Issue: Microsoft Graph Beta API endpoints may change without notice, including:

Schema changes
New required fields
Deprecated fields
Endpoint URL changes
Behavior changes

Status: Microsoft Documented - Beta API subject to changeWorkarounds:

Pin Provider Version: Use exact version constraints in production:

terraform {
  required_providers {
    microsoft365 = {
      source  = "deploymenttheory/microsoft365"
      version = "= 0.46.0-alpha"
    }
  }
}

Test Before Upgrading: Always test provider upgrades in non-production environments
Monitor Release Notes: Review changelog for breaking changes
Prefer v1.0 When Available: Use Graph v1.0 resources when stable alternatives exist

Additional Notes: This is expected behavior for beta APIs. Microsoft recommends using v1.0 endpoints for production workloads.

Provider-Specific Limitations

[PROV-001] Alpha Release Status

Impact Level: HighIssue: The provider is in alpha release (v0.x.x-alpha). Breaking changes may occur between minor versions during this phase.Affected:

All resources and data sources

Status: Expected - Alpha development phaseRecommendations:

Pin Exact Versions: Use version = "= X.X.X-alpha" in production
Test Upgrades: Always test provider version upgrades in dev/staging first
Review Changelogs: Check release notes for breaking changes before upgrading
Backup State: Maintain Terraform state backups before upgrades
CI/CD Integration: Include provider version in CI/CD pipelines for consistency

Migration to Stable: The provider will eventually move to stable (v1.0.0+) release. Migration guides will be provided for breaking changes.

[PROV-002] Large Resource Updates

Impact Level: LowIssue: Resources with very large configuration blocks (e.g., Settings Catalog policies with hundreds of settings) may experience longer apply times.Affected Resources:

microsoft365_graph_beta_device_management_settings_catalog_configuration_policy_json
Resources with complex nested blocks

Status: Known limitation - Optimization ongoingWorkarounds:

Increase Timeouts: Configure longer timeouts for large resources:

resource "microsoft365_graph_beta_device_management_settings_catalog_configuration_policy_json" "large_policy" {
  # ... configuration ...
  
  timeouts {
    create = "30m"
    update = "30m"
    read   = "10m"
  }
}

Split Policies: Break very large policies into multiple smaller policies if possible
Batch Updates: Group related changes together rather than frequent small updates

Issue Status Definitions

Open

status

Issue identified but not yet investigated

Investigating

status

Provider team is researching the issue

Microsoft Acknowledged

status

Microsoft has acknowledged the underlying API issue

Fixed in Graph

status

Microsoft has fixed the underlying API issue

Workaround Available

status

Temporary solution is available

Closed

status

Issue has been resolved

Impact Level Definitions

Level	Description
Critical	Complete functionality failure, no workaround available
High	Major functionality impaired, limited workarounds
Medium	Functionality affected but workarounds available
Low	Minor inconvenience, easy workarounds available

Contributing to Issue Tracking

When contributing to this document:

Use the Template

Follow the issue template format for consistency

Assign Bug IDs

Use sequential IDs (BUG-001, BUG-002, GRAPH-001, PROV-001)

Complete Information

Include all required fields - don’t leave sections empty

Verify Before Adding

Check for duplicates before documenting new issues

Update Regularly

Keep status and workarounds current as issues evolve

Link Resources

Link to related GitHub issues and Microsoft docs

Helpful Resources

Microsoft Graph Known Issues

Official Microsoft Graph API known issues documentation

Graph Feedback Portal

Submit feedback and feature requests to Microsoft

Provider GitHub Issues

Report provider-specific issues and bugs

M365 Service Health

Check Microsoft 365 service health and incidents

Getting Help

If you need assistance with an issue:

Check this documentation for known issues and workarounds
Search GitHub Issues for similar problems
Join the Discord community for real-time help: discord.gg/Uq8zG6g7WE
Create a GitHub Issue with detailed reproduction steps
Contact Microsoft Support for Graph API-specific issues (if you have a support contract)

Changelog - Version history and bug fixes
Provider Roadmap - Planned improvements
Development Guide - Contributing fixes
Contributing Guide - How to contribute

Provider

Development

Examples

How to Report Issues

Issue Tracking Template

Current Known Issues

Microsoft Graph API Limitations

Provider-Specific Limitations

Issue Status Definitions

Impact Level Definitions

Contributing to Issue Tracking

Use the Template

Assign Bug IDs

Complete Information

Verify Before Adding

Update Regularly

Link Resources

Helpful Resources

Microsoft Graph Known Issues

Graph Feedback Portal

Provider GitHub Issues

M365 Service Health

Getting Help

Build docs developers (and LLMs) love

Provider

Development

Examples

​How to Report Issues

​Issue Tracking Template

​Current Known Issues

​Microsoft Graph API Limitations

​Provider-Specific Limitations

​Issue Status Definitions

​Impact Level Definitions

​Contributing to Issue Tracking

Use the Template

Assign Bug IDs

Complete Information

Verify Before Adding

Update Regularly

Link Resources

​Helpful Resources

Microsoft Graph Known Issues

Graph Feedback Portal

Provider GitHub Issues

M365 Service Health

​Getting Help

​Related Resources

Build docs developers (and LLMs) love

How to Report Issues

Issue Tracking Template

Current Known Issues

Microsoft Graph API Limitations

Provider-Specific Limitations

Issue Status Definitions

Impact Level Definitions

Contributing to Issue Tracking

Helpful Resources

Getting Help

Related Resources