Skip to content

Conversation

Copy link
Contributor

Copilot AI commented Nov 20, 2025

Consolidates troubleshooting patterns from 181+ closed issues into a structured reference guide for GitHub Copilot, maintainers, and contributors.

Document Structure

.github/copilot-issue-guidelines.md (1,461 lines)

Issue Categories with Symptom → Root Cause → Solution Patterns

  • Authentication Flow Failures - Redirect URI encoding mismatches, browser requirements, callback lifecycle issues
  • Initialization/Manifest/Config - JSON validation, file placement, client ID format, intent filter configuration
  • Token Acquisition & Refresh - Account caching, scope validation, token expiration, claims configuration
  • Broker & Company Portal - Installation verification, signature hash matching, SSO setup
  • Device/SSO/Registration - Azure AD device registration, Intune enrollment, MAM policies
  • Crashes & ANRs - Null safety in callbacks, fragment lifecycle, threading, memory leaks

Support Materials

  • Universal Troubleshooting Checklist - 35+ verification points covering configuration, Azure AD, code implementation
  • 7 Response Templates - Initial response, configuration errors, token issues, broker problems, crashes, resolution, escalation
  • Error Code Reference Table - 10 frequent MSAL errors with immediate fixes
  • 77 Code Examples - Correct patterns vs. common mistakes

Example Usage

### Symptom: NO_ACCOUNT_FOUND Error

**Root Cause:** No cached account exists

**Solution:**
```java
// Must use interactive acquireToken first
AcquireTokenParameters params = new AcquireTokenParameters.Builder()
    .startAuthorizationFromActivity(activity)
    .withScopes(Arrays.asList("User.Read"))
    .withCallback(callback)
    .build();
mPCA.acquireToken(params);

Enables consistent, code-specific responses with reduced diagnosis time.

<!-- START COPILOT CODING AGENT SUFFIX -->



<details>

<summary>Original prompt</summary>

> Create a new file named .github/copilot-issue-guidelines.md in the repository. The file should include consolidated troubleshooting and response guidance for Copilot and maintainers, spanning frequent errors, root causes, solutions, and answer templates found in 181 closed issues tagged with errors, crashes, and unexpected behavior. Guidelines should include grouped entries for auth flow failures, initialization/manifest/config problems, token issues, broker/company portal problems, device/SSO/registration, crashes/ANRs, and a universal troubleshooting checklist, using markdown structure as previously drafted.


</details>

*This pull request was created as a result of the following prompt from Copilot chat.*
> Create a new file named .github/copilot-issue-guidelines.md in the repository. The file should include consolidated troubleshooting and response guidance for Copilot and maintainers, spanning frequent errors, root causes, solutions, and answer templates found in 181 closed issues tagged with errors, crashes, and unexpected behavior. Guidelines should include grouped entries for auth flow failures, initialization/manifest/config problems, token issues, broker/company portal problems, device/SSO/registration, crashes/ANRs, and a universal troubleshooting checklist, using markdown structure as previously drafted.

<!-- START COPILOT CODING AGENT TIPS -->
---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://gh.io/copilot-coding-agent-survey).

Copilot AI changed the title [WIP] Add Copilot issue troubleshooting guidelines Add comprehensive issue troubleshooting guidelines for MSAL Android Nov 20, 2025
Copilot AI requested a review from fadidurah November 20, 2025 18:09
Copilot finished work on behalf of fadidurah November 20, 2025 18:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants