| name | notion-advanced-troubleshooting |
| description | Use when standard Notion troubleshooting fails or you are chasing intermittent
API errors — deep debugging for response inspection, permission chain tracing,
property type mismatches, pagination edge cases, and block nesting limits.
Trigger with phrases like "notion deep debug", "notion permission trace",
"notion property mismatch", "notion pagination bug", "notion nesting limit".
|
| allowed-tools | Read, Grep, Bash(curl:*), Bash(node:*) |
| version | 1.38.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","productivity","notion"] |
| compatibility | Designed for Claude Code |
Notion Advanced Troubleshooting
Overview
Deep debugging techniques for Notion API issues that resist standard fixes —
API response inspection with request IDs, permission chain tracing, property
type mismatch detection, pagination edge cases, and block nesting limit
violations (max depth of 3 levels via API). Full runnable TypeScript and Python
for every step lives in references/implementation.md.
Prerequisites
@notionhq/client v2.x installed (npm install @notionhq/client)- Python:
notion-client installed (pip install notion-client)
curl available for raw API testingNOTION_TOKEN environment variable set (internal integration token starting with ntn_)- Pages/databases shared with your integration via Notion UI
Authentication
All calls authenticate with a single internal integration token in the
NOTION_TOKEN environment variable — the SDK reads it via auth: process.env.NOTION_TOKEN, and raw curl sends it as
Authorization: Bearer $NOTION_TOKEN plus the Notion-Version: 2022-06-28
header. Never hardcode the token; keep it in the environment. Confirm the token
is a bot token with notion.users.me() — if the returned type is not bot,
the token is wrong. A 401 unauthorized means a bad/expired token; a 404 object_not_found on a valid page means the token is fine but the resource
was never shared with the integration (see Step 2).
Instructions
Work the steps in order — each narrows where the failure lives. Read the
full walkthrough for the complete function
bodies; the skeletons below show the entry point of each.
Step 1: API Response Inspection with Request ID Tracking
Every Notion API response carries an x-request-id header. Enable
LogLevel.DEBUG and wrap calls so every request logs its ID and timing —
capture that ID for support tickets. Use Grep over the debug log to find a
specific request's ID after the fact.
const notion = new Client({ auth: process.., : . });
tracedCall<T>(: , : <T>) {
start = .();
{
result = ();
.();
result;
} (error) {
((error)) .(, error., error.);
error;
}
}
