Add BadGateway error troubleshooting documentation for solution imports

[Copilot]

Users upgrading CoE Starter Kit encounter BadGateway (HTTP 502) errors during solution import, specifically when importing flows. This is a transient Power Platform service error, not a CoE Starter Kit bug, but lacks documentation.

Changes

Comprehensive troubleshooting guide (docs/troubleshooting/solution-import-badgateway.md)

• Root cause analysis: transient Power Automate backend unavailability
• Primary resolution: wait 30-60 minutes, retry import
• Advanced options: PAC CLI import, off-peak retry strategy, Microsoft Support escalation criteria
• FAQ covering distinction from TooManyRequests (429) and other error types

Quick reference integration (TROUBLESHOOTING-UPGRADES.md)

• Added BadGateway section to "Quick Fixes" with immediate steps
• Linked to comprehensive guide for detailed troubleshooting

Response templates

• docs/ISSUE-RESPONSE-BadGateway-Import.md: maintainer template for consistent responses
• docs/USER-RESPONSE-BadGateway-Issue.md: ready-to-use response for reported issues
• docs/IMPLEMENTATION-SUMMARY-BadGateway.md: technical analysis and solution rationale

Error Example

Solution 'Center of Excellence - Core Components' failed to import: 
ImportAsHolding failed with exception: Error while importing workflow 
{1edb4715-b85b-ed11-9561-0022480819d7} type ModernFlow name 
HELPER - Add User to Security Role. Flow server error returned with 
status code 'BadGateway' and details.

Resolution: Retry after 30-60 minutes. BadGateway indicates temporary service unavailability, not configuration or code issues. Safe to retry - no data loss or duplication risk.

Impact

• Reduces duplicate issue reports for transient service errors
• Provides clear escalation path (retry → off-peak → Microsoft Support)
• Distinguishes service errors from application bugs
• Template establishes pattern for documenting other HTTP error codes (500, 503, etc.)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[CoE Starter Kit - BUG] ISSUE TITLE</issue_title>
<issue_description>### Does this bug already exist in our backlog?

• I have checked and confirm this is a new bug.

Describe the issue

During the upgrade of the COE from Core Components 4.50.2 to CenterofExcellenceCoreComponents_4.50.6, I keep encountering the following error:

"Solution 'Center of Excellence - Core Components' failed to import: ImportAsHolding failed with exception: Error while importing workflow {1edb4715-b85b-ed11-9561-0022480819d7} type ModernFlow name HELPER - Add User to Security Role. Flow server error returned with status code 'BadGateway' and details.".

Expected Behavior

No response

What solution are you experiencing the issue with?

Core

What solution version are you using?

Center of Excellence - Core Components 4.50.2

What app or flow are you having the issue with?

Upgrading to the latest coe version

What method are you using to get inventory and telemetry?

Cloud flows

Steps To Reproduce

Anything else?

No response</issue_description>

<agent_instructions>Analyze why upgrading CoE Core from 4.50.2 to 4.50.6 fails with ‘BadGateway’ while importing the modern flow HELPER – Add User to Security Role (workflow id {1edb4715-b85b-ed11-9561-0022480819d7}). Identify the root cause (e.g., connector auth, service throttling, environment/tenant limits, or missing permissions) and provide supported steps/workarounds to complete the import successfully.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Custom agent used: CoE Custom Agent
Specialized agent for triaging and fixing issues in the CoE Starter Kit. Always consult the official CoE docs and the team’s SharePoint notes first, then mine prior GitHub issues and the CoE Common Responses playbook.

• Fixes [CoE Starter Kit - BUG] ISSUE TITLE #10773

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.