Skip to main content
onenote-debug-bundle Generate comprehensive diagnostic bundles for OneNote Graph API issues with request tracing and token analysis.
Use when debugging OneNote API failures, filing Microsoft support tickets, or analyzing permission issues.
Trigger with "onenote debug", "onenote diagnostic", "onenote support ticket", "graph api troubleshoot onenote".
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/jeremylongshore/claude-code-plugins-plus-skills --skill onenote-debug-bundleThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... More from this repository
Related occupations SOC
Based on SOC occupation classification
name onenote-debug-bundle description Generate comprehensive diagnostic bundles for OneNote Graph API issues with request tracing and token analysis.
Use when debugging OneNote API failures, filing Microsoft support tickets, or analyzing permission issues.
Trigger with "onenote debug", "onenote diagnostic", "onenote support ticket", "graph api troubleshoot onenote".
allowed-tools Read, Write, Edit, Bash(npm:*), Bash(pip:*), Grep version 1.6.0 license MIT author Jeremy Longshore <jeremy@intentsolutions.io> tags ["saas","onenote","microsoft"] compatibility Designed for Claude Code
OneNote Debug Bundle
Overview
When OneNote API calls fail, you need the request-id response header (Microsoft support requires it), decoded JWT token claims (to verify granted scopes), the x-ms-ags-diagnostic header (internal Graph routing info), and the full error body — all correlated to a single request. This skill generates structured diagnostic bundles for self-diagnosis and Microsoft support ticket filing.
Prerequisites
Node.js 18+ or Python 3.10+
An existing OneNote integration with Graph API calls
@microsoft/microsoft-graph-client or msgraph-sdk installedAccess token available (for token inspection)
Instructions
TypeScript Diagnostic Middleware
Intercept all Graph API calls and capture diagnostics automatically:
interface DiagnosticEntry {
timestamp : string ; method : string ; url : string ; status : number ;
requestId : string | null ; agsDiagnostic : string | null ;
retryAfter : string | null ; duration_ms : number ; error : any | null ;
}
const diagnosticLog : DiagnosticEntry [] = [];
export function createDiagnosticMiddleware (return {
execute : async (context
any
const
Date
now
const
request
url
"unknown"
method
"GET"
try
await
next
const
response
headers
push
timestamp
new
Date
toISOString
status
response
status
0
requestId
get
"request-id"
null
agsDiagnostic
get
"x-ms-ags-diagnostic"
null
retryAfter
get
"retry-after"
null
duration_ms
Date
now
error
null
catch
err
any
push
timestamp
new
Date
toISOString
status
statusCode
0
requestId
headers
"request-id"
null
agsDiagnostic
headers
"x-ms-ags-diagnostic"
null
retryAfter
headers
"retry-after"
null
duration_ms
Date
now
error
code
code
message
message
body
body
throw
export
function
getDiagnosticLog
DiagnosticEntry
return
export
function
clearDiagnosticLog
void
length
0
Token Claims Inspection (No External Libraries) Decode a JWT access token to inspect scopes and expiry using only built-in Base64:
export function decodeTokenClaims (accessToken : string Record <string , any > {
const parts = accessToken.split ("." );
if (parts.length !== 3 ) throw new Error ("Invalid JWT: expected 3 dot-separated parts" );
const base64 = parts[1 ].replace (/-/g , "+" ).replace (/_/g , "/" );
const padded = base64 + "=" .repeat ((4 - (base64.length % 4 )) % 4 );
return JSON .parse (Buffer .from (padded, "base64" ).toString ("utf-8" ));
}
export function analyzePermissions (claims : Record <string , any >, required : string []const granted = claims.scp ? claims.scp .split (" " ) : (claims.roles || []);
const missing = required.filter ((s ) => !granted.includes (s));
const now = Math .floor (Date .now () / 1000 );
const isExpired = claims.exp < now;
const diff = Math .abs (claims.exp - now);
const expiresIn = isExpired ? `Expired ${diff} s ago` : `${Math .floor(diff / 60 )} m remaining` ;
return { granted, missing, isExpired, expiresIn };
}
Python Diagnostic Context Manager
import json, base64, time
from datetime import datetime, timezone
from dataclasses import dataclass, asdict
from typing import Optional
@dataclass
class DiagnosticCapture :
timestamp: str ; method: str ; url: str ; status: int
request_id: Optional [str ]; ags_diagnostic: Optional [str ]
retry_after: Optional [str ]; duration_ms: float
error_code: Optional [str ]; error_message: Optional [str ]
class GraphDiagnostics :
def __init__ (self ):
self .captures: list [DiagnosticCapture] = []
async def capture_request (self, client, method: str , endpoint: str , **kwargs ):
url = f"https://graph.microsoft.com/v1.0{endpoint} "
start = time.monotonic()
try :
response = await client.api(endpoint).get() if method == "GET" \
else await client.api(endpoint).post(kwargs.get("body" ))
self .captures.append(DiagnosticCapture(
datetime.now(timezone.utc).isoformat(), method, url, 200 ,
None , None , None , round ((time.monotonic()-start)*1000 , 2 ), None , None ))
return response
except Exception as e:
headers = getattr (e, "headers" , {}) or {}
self .captures.append(DiagnosticCapture(
datetime.now(timezone.utc).isoformat(), method, url,
int (getattr (e, "status_code" , 0 )),
headers.get("request-id" ), headers.get("x-ms-ags-diagnostic" ),
headers.get("retry-after" ), round ((time.monotonic()-start)*1000 , 2 ),
str (getattr (e, "code" , type (e).__name__)), str (e)))
raise
def export_bundle (self, filepath: str , token: Optional [str ] = None ) -> str :
bundle = {"bundle_version" : "1.0" , "generated" : datetime.now(timezone.utc).isoformat(),
"captures" : [asdict(c) for c in self .captures]}
if token:
parts = token.split("." )
bundle["token_claims" ] = json.loads(base64.urlsafe_b64decode(parts[1 ] + "==" ))
with open (filepath, "w" ) as f:
json.dump(bundle, f, indent=2 )
return filepath
Microsoft Support Ticket Template When filing a support case, include this from the diagnostic bundle:
Subject: OneNote Graph API - [Error Code] on [Endpoint]
1. Request ID: [from request-id response header]
2. Timestamp (UTC): [from diagnostic bundle]
3. Tenant ID: [from token claims tid]
4. App ID: [from token claims azp]
5. Endpoint: GET /me/onenote/notebooks
6. HTTP Status: 403
7. Error Code: ErrorAccessDenied
8. Error Message: Access is denied.
9. x-ms-ags-diagnostic: [full header value]
10. Token scopes granted: Notes.Read User.Read
11. Expected scopes: Notes.ReadWrite
12. SDK version: @microsoft/microsoft-graph-client@3.0.7
Common Diagnostic Patterns "Why is my 403 happening?" — Decode token, compare scopes:
const claims = decodeTokenClaims (accessToken);
const { missing, isExpired, expiresIn } = analyzePermissions (claims, ["Notes.ReadWrite" ]);
if (missing.length > 0 ) console .error (`Missing scopes: ${missing.join(", " )} ` );
if (isExpired) console .error (`Token expired: ${expiresIn} ` );
"Which request failed in a batch?" — Filter diagnostic log:
const failures = getDiagnosticLog ().filter ((e ) => e.status >= 400 );
failures.forEach ((f ) => console .error (`[${f.requestId} ] ${f.method} ${f.url} -> ${f.status} ` ));
Output
src/debug/diagnostic-middleware.ts — automatic Graph API call interceptionsrc/debug/token-inspector.ts — JWT decode and permission analysis (zero dependencies)debug/diagnostic_capture.py — Python diagnostic context manager with bundle exportDiagnostic bundle JSON file with request-id, token claims, and error details
Microsoft support ticket template with required fields
Error Handling Debug Issue Cause Fix request-id is nullResponse headers not captured Use diagnostic middleware; direct fetch bypasses header capture JWT decode fails Token is opaque (v1) Graph tokens should be v2 JWT; check aud matches https://graph.microsoft.com scp claim emptyApp-only token (no delegated scopes) App-only auth deprecated March 2025; switch to delegated x-ms-ags-diagnostic missingNot all errors include it Optional header; rely on request-id for support tickets Wrong tenant in claims Multi-tenant app resolving wrong Verify AZURE_TENANT_ID; check tid claim
Examples
import { getDiagnosticLog } from "./debug/diagnostic-middleware" ;
import { decodeTokenClaims, analyzePermissions } from "./debug/token-inspector" ;
import { writeFileSync } from "fs" ;
const bundle = {
bundle_version : "1.0" , timestamp : new Date ().toISOString (),
log : getDiagnosticLog (),
token : analyzePermissions (decodeTokenClaims (token), ["Notes.Read" , "Notes.ReadWrite" ]),
};
writeFileSync (`onenote-debug-${Date .now()} .json` , JSON .stringify (bundle, null , 2 ));
node -e "
const t = process.env.GRAPH_TOKEN;
const p = JSON.parse(Buffer.from(t.split('.')[1].replace(/-/g,'+').replace(/_/g,'/'), 'base64'));
console.log('Scopes:', p.scp, '| Expires:', new Date(p.exp*1000).toISOString());
"
Resources
Next Steps
Fix common errors with onenote-common-errors
Tune performance after diagnosing bottlenecks with onenote-performance-tuning
Check rate limit patterns with onenote-rate-limits
