[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M793H4GWSMPWHKBZ64KM1TK6":3,"skill-same:01M793H4GWSMPWHKBZ64KM1TK6":56},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":33,"commitSha":34,"skillDirectory":35,"forksCount":36,"repositoryHtmlUrl":37,"repositoryHomepageUrl":6,"ownerHtmlUrl":38,"ownerBlogUrl":39,"ownerDescription":40,"updatedAt":41,"install":42,"resources":55},"01M793H4GWSMPWHKBZ64KM1TK6","notion-advanced-troubleshooting",null,"Deep debugging for Notion API: response inspection, permission chain tracing,\nproperty type mismatches, pagination edge cases, and block nesting limits.\nUse when standard troubleshooting fails or investigating intermittent errors.\nTrigger with phrases like \"notion deep debug\", \"notion permission trace\",\n\"notion property mismatch\", \"notion pagination bug\", \"notion nesting limit\".","jukeyman\u002Fjukeyman-skills","jukeyman","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F142960420?v=4","01M78FR4Y3DHMMCBCC0GXXNB3F","RICK JEFFERSON","01M78FR4Z8RVQRAD31Y5J7V6EB",1,"MIT","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsaas-packs--notion-pack--notion-advanced-troubleshooting\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: notion-advanced-troubleshooting\ndescription: |\n  Deep debugging for Notion API: response inspection, permission chain tracing,\n  property type mismatches, pagination edge cases, and block nesting limits.\n  Use when standard troubleshooting fails or investigating intermittent errors.\n  Trigger with phrases like \"notion deep debug\", \"notion permission trace\",\n  \"notion property mismatch\", \"notion pagination bug\", \"notion nesting limit\".\nallowed-tools: Read, Grep, Bash(curl:*), Bash(node:*)\nversion: 1.0.0\nlicense: MIT\nauthor: Jeremy Longshore \u003Cjeremy@intentsolutions.io>\ntags: [saas, productivity, notion]\ncompatible-with: claude-code\n---\n\n# Notion Advanced Troubleshooting\n\n## Overview\n\nDeep debugging techniques for Notion API issues that resist standard fixes. Covers API response inspection with request IDs, permission chain tracing through page hierarchies, property type mismatch detection against database schemas, pagination edge cases with cursor validation, and block nesting limit violations (max depth of 3 levels via API). Uses `Client` from `@notionhq\u002Fclient` and raw `curl` for comparison testing.\n\n## Prerequisites\n\n- `@notionhq\u002Fclient` v2.x installed (`npm install @notionhq\u002Fclient`)\n- Python: `notion-client` installed (`pip install notion-client`)\n- `curl` available for raw API testing\n- `NOTION_TOKEN` environment variable set (internal integration token starting with `ntn_`)\n- Pages\u002Fdatabases shared with your integration via Notion UI\n\n## Instructions\n\n### Step 1: API Response Inspection with Request ID Tracking\n\nEvery Notion API response includes an `x-request-id` header. Capture it for debugging and support tickets.\n\n```typescript\nimport { Client, LogLevel, isNotionClientError, APIErrorCode } from '@notionhq\u002Fclient';\n\nconst notion = new Client({\n  auth: process.env.NOTION_TOKEN,\n  logLevel: LogLevel.DEBUG, \u002F\u002F Logs full request\u002Fresponse to stderr\n});\n\n\u002F\u002F Wrapper that captures request ID and timing for every call\nasync function tracedCall\u003CT>(\n  label: string,\n  fn: () => Promise\u003CT>\n): Promise\u003C{ result: T; durationMs: number }> {\n  const start = Date.now();\n  try {\n    const result = await fn();\n    const durationMs = Date.now() - start;\n    console.log(`[${label}] OK ${durationMs}ms`);\n    return { result, durationMs };\n  } catch (error) {\n    const durationMs = Date.now() - start;\n    if (isNotionClientError(error)) {\n      console.error(`[${label}] FAILED ${durationMs}ms`, {\n        code: error.code,\n        status: error.status,\n        message: error.message,\n        body: error.body,\n      });\n    }\n    throw error;\n  }\n}\n\n\u002F\u002F Compare SDK vs raw curl to isolate SDK issues\n\u002F\u002F Run in bash alongside:\n\u002F\u002F curl -v https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fpages\u002FPAGE_ID \\\n\u002F\u002F   -H \"Authorization: Bearer $NOTION_TOKEN\" \\\n\u002F\u002F   -H \"Notion-Version: 2022-06-28\" 2>&1 | grep x-request-id\n```\n\n```python\nfrom notion_client import Client\nimport logging\n\n# Enable debug logging for full request\u002Fresponse visibility\nlogging.basicConfig(level=logging.DEBUG)\nnotion = Client(auth=os.environ[\"NOTION_TOKEN\"], log_level=logging.DEBUG)\n\n# Traced wrapper for Python\nimport time\n\ndef traced_call(label: str, fn):\n    start = time.time()\n    try:\n        result = fn()\n        duration = (time.time() - start) * 1000\n        print(f\"[{label}] OK {duration:.0f}ms\")\n        return result\n    except Exception as e:\n        duration = (time.time() - start) * 1000\n        print(f\"[{label}] FAILED {duration:.0f}ms: {e}\")\n        raise\n```\n\n### Step 2: Permission Chain Tracing\n\nWhen you get `object_not_found` (404), the page exists but your integration lacks access. Trace the permission chain up the page hierarchy.\n\n```typescript\nasync function tracePermissionChain(pageId: string): Promise\u003Cvoid> {\n  console.log(`\\n=== Permission Chain Trace for ${pageId} ===`);\n  let currentId = pageId;\n  let depth = 0;\n\n  while (currentId && depth \u003C 10) {\n    try {\n      const page = await notion.pages.retrieve({ page_id: currentId });\n      const parent = (page as any).parent;\n      console.log(`  ${'  '.repeat(depth)}[${depth}] Page ${currentId} - ACCESSIBLE`);\n      console.log(`  ${'  '.repeat(depth)}    Parent type: ${parent.type}`);\n\n      if (parent.type === 'database_id') {\n        \u002F\u002F Check database access too\n        try {\n          await notion.databases.retrieve({ database_id: parent.database_id });\n          console.log(`  ${'  '.repeat(depth)}    Database ${parent.database_id} - ACCESSIBLE`);\n        } catch {\n          console.log(`  ${'  '.repeat(depth)}    Database ${parent.database_id} - NO ACCESS`);\n        }\n        break;\n      } else if (parent.type === 'page_id') {\n        currentId = parent.page_id;\n      } else if (parent.type === 'workspace') {\n        console.log(`  ${'  '.repeat(depth)}    Root: workspace`);\n        break;\n      } else {\n        break;\n      }\n      depth++;\n    } catch (error) {\n      if (isNotionClientError(error) && error.code === APIErrorCode.ObjectNotFound) {\n        console.log(`  ${'  '.repeat(depth)}[${depth}] Page ${currentId} - NO ACCESS (object_not_found)`);\n        console.log(`  ${'  '.repeat(depth)}    Fix: Open this page in Notion → ··· → Connections → Add your integration`);\n      } else {\n        console.log(`  ${'  '.repeat(depth)}[${depth}] Page ${currentId} - ERROR: ${(error as Error).message}`);\n      }\n      break;\n    }\n  }\n}\n\n\u002F\u002F Also verify bot identity and capabilities\nconst me = await notion.users.me({});\nconsole.log('Bot user:', me.name, '| Type:', me.type);\n\u002F\u002F If me.type !== 'bot', your token is wrong\n```\n\n```python\ndef trace_permission_chain(page_id: str):\n    \"\"\"Walk up the page hierarchy to find where access breaks.\"\"\"\n    current_id = page_id\n    depth = 0\n\n    while current_id and depth \u003C 10:\n        try:\n            page = notion.pages.retrieve(page_id=current_id)\n            parent = page[\"parent\"]\n            print(f\"  [depth={depth}] {current_id} - ACCESSIBLE (parent: {parent['type']})\")\n\n            if parent[\"type\"] == \"database_id\":\n                try:\n                    notion.databases.retrieve(database_id=parent[\"database_id\"])\n                    print(f\"  [depth={depth}] Database {parent['database_id']} - ACCESSIBLE\")\n                except Exception:\n                    print(f\"  [depth={depth}] Database {parent['database_id']} - NO ACCESS\")\n                break\n            elif parent[\"type\"] == \"page_id\":\n                current_id = parent[\"page_id\"]\n            else:\n                break\n            depth += 1\n        except Exception as e:\n            print(f\"  [depth={depth}] {current_id} - NO ACCESS: {e}\")\n            print(f\"  Fix: Share this page with your integration in Notion UI\")\n            break\n```\n\n### Step 3: Property Type Mismatch Detection and Pagination Edge Cases\n\nThe most common `validation_error` comes from sending the wrong property type. Validate against the live schema before creating\u002Fupdating.\n\n```typescript\n\u002F\u002F Detect property type mismatches against live database schema\nasync function detectPropertyMismatches(\n  databaseId: string,\n  properties: Record\u003Cstring, unknown>\n): Promise\u003Cstring[]> {\n  const db = await notion.databases.retrieve({ database_id: databaseId });\n  const schema = db.properties;\n  const issues: string[] = [];\n\n  \u002F\u002F Check each property you're trying to set\n  for (const [name, value] of Object.entries(properties)) {\n    if (!schema[name]) {\n      issues.push(\n        `Property \"${name}\" not found. Available: ${Object.keys(schema).join(', ')}`\n      );\n      continue;\n    }\n\n    const expectedType = schema[name].type;\n    const sentType = Object.keys(value as object).find(k =>\n      ['title', 'rich_text', 'number', 'select', 'multi_select',\n       'date', 'checkbox', 'url', 'email', 'phone_number',\n       'people', 'relation', 'files', 'status'].includes(k)\n    );\n\n    if (sentType && sentType !== expectedType) {\n      issues.push(\n        `\"${name}\": schema type is \"${expectedType}\" but you sent \"${sentType}\"`\n      );\n    }\n  }\n\n  \u002F\u002F Check for missing title property (required for page creation)\n  const titleProp = Object.entries(schema).find(([, v]) => v.type === 'title');\n  if (titleProp && !properties[titleProp[0]]) {\n    issues.push(`Missing required title property \"${titleProp[0]}\"`);\n  }\n\n  return issues;\n}\n\n\u002F\u002F Pagination edge cases: cursor validation and empty page handling\nasync function safeFullPagination(databaseId: string, filter?: any) {\n  const allResults: any[] = [];\n  let cursor: string | undefined;\n  let pageCount = 0;\n  const MAX_PAGES = 1000; \u002F\u002F Safety valve: 100K records max\n\n  do {\n    if (pageCount >= MAX_PAGES) {\n      console.warn(`Pagination safety limit reached (${MAX_PAGES} pages, ${allResults.length} results)`);\n      break;\n    }\n\n    const response = await notion.databases.query({\n      database_id: databaseId,\n      filter,\n      page_size: 100,\n      start_cursor: cursor,\n    });\n\n    allResults.push(...response.results);\n    pageCount++;\n\n    \u002F\u002F Edge case: has_more is true but next_cursor is null (API bug, rare)\n    if (response.has_more && !response.next_cursor) {\n      console.warn('Pagination anomaly: has_more=true but next_cursor is null');\n      break;\n    }\n\n    cursor = response.has_more ? (response.next_cursor ?? undefined) : undefined;\n\n    \u002F\u002F Rate limit compliance: ~3 req\u002Fs\n    await new Promise(r => setTimeout(r, 350));\n  } while (cursor);\n\n  console.log(`Paginated ${pageCount} pages, ${allResults.length} total results`);\n  return allResults;\n}\n\n\u002F\u002F Block nesting limit detection\n\u002F\u002F Notion API allows max 3 levels of nested blocks (API limitation)\n\u002F\u002F UI supports deeper nesting, but API cannot create\u002Fread beyond depth 3\nasync function checkBlockNesting(blockId: string, depth = 0): Promise\u003Cnumber> {\n  if (depth >= 3) {\n    console.warn(`Block nesting limit reached at depth ${depth} (API max is 3)`);\n    return depth;\n  }\n\n  const children = await notion.blocks.children.list({ block_id: blockId });\n  let maxDepth = depth;\n\n  for (const block of children.results) {\n    if ((block as any).has_children) {\n      const childDepth = await checkBlockNesting((block as any).id, depth + 1);\n      maxDepth = Math.max(maxDepth, childDepth);\n    }\n  }\n\n  return maxDepth;\n}\n```\n\n```python\ndef detect_property_mismatches(database_id: str, properties: dict) -> list[str]:\n    \"\"\"Validate properties against live database schema.\"\"\"\n    db = notion.databases.retrieve(database_id=database_id)\n    schema = db[\"properties\"]\n    issues = []\n\n    for name, value in properties.items():\n        if name not in schema:\n            available = \", \".join(schema.keys())\n            issues.append(f'Property \"{name}\" not found. Available: {available}')\n            continue\n\n        expected_type = schema[name][\"type\"]\n        sent_types = [k for k in value.keys() if k in\n            (\"title\", \"rich_text\", \"number\", \"select\", \"multi_select\",\n             \"date\", \"checkbox\", \"url\", \"email\", \"status\")]\n        if sent_types and sent_types[0] != expected_type:\n            issues.append(f'\"{name}\": expected \"{expected_type}\", got \"{sent_types[0]}\"')\n\n    # Check for missing title\n    title_props = [k for k, v in schema.items() if v[\"type\"] == \"title\"]\n    if title_props and title_props[0] not in properties:\n        issues.append(f'Missing required title property \"{title_props[0]}\"')\n\n    return issues\n```\n\n## Output\n\n- Request IDs captured for every API call with timing data\n- Permission chain traced from target page up to workspace root\n- Property type mismatches detected before they cause validation errors\n- Pagination edge cases handled (null cursors, safety limits)\n- Block nesting depth verified against API 3-level limit\n\n## Error Handling\n\n| Symptom | Root Cause | Debug Approach |\n|---------|-----------|----------------|\n| `object_not_found` on valid page | Page not shared with integration | Run `tracePermissionChain()` |\n| `validation_error` on create\u002Fupdate | Property type mismatch | Run `detectPropertyMismatches()` |\n| Missing data from query | Not paginating (max 100\u002Frequest) | Use `safeFullPagination()` |\n| `could not find block` at depth 4+ | API nesting limit (3 levels) | Flatten block structure |\n| Works in curl, fails in SDK | SDK header or payload difference | Enable `LogLevel.DEBUG`, compare |\n| Intermittent 500 errors | Notion server issues | Capture `x-request-id`, retry with backoff |\n| `rate_limited` (429) | Exceeding 3 req\u002Fs | Add 350ms delay between calls |\n| `conflict_error` | Concurrent page update | Retry with fresh page read |\n\n## Examples\n\n### Minimal Reproduction Script\n\n```typescript\n\u002F\u002F Strip to bare minimum to isolate the issue\nasync function minimalRepro() {\n  const notion = new Client({\n    auth: process.env.NOTION_TOKEN,\n    logLevel: LogLevel.DEBUG,\n  });\n\n  \u002F\u002F 1. Auth check\n  const me = await notion.users.me({});\n  console.log('Auth OK:', me.name);\n\n  \u002F\u002F 2. Search check (proves token works)\n  const search = await notion.search({ page_size: 1 });\n  console.log('Search OK:', search.results.length, 'results');\n\n  \u002F\u002F 3. Specific resource check\n  const db = await notion.databases.retrieve({\n    database_id: process.env.NOTION_DB_ID!,\n  });\n  console.log('DB OK:', Object.keys(db.properties).join(', '));\n\n  \u002F\u002F 4. The failing operation — insert exact failing call here\n}\n\nminimalRepro().catch(console.error);\n```\n\n### Support Escalation Template\n\n```\nSubject: [Request ID: abc123] validation_error on pages.create\nEnvironment: Node.js 20, @notionhq\u002Fclient 2.2.15, API 2022-06-28\nIntegration ID: [from notion.so\u002Fprofile\u002Fintegrations]\nRequest ID: [from x-request-id header or error body]\nTimestamp: 2026-03-22T14:30:00Z\n\nSteps: POST \u002Fv1\u002Fpages with body: { ... }\nExpected: 200 with page object\nActual: 400 validation_error \"...\"\nFrequency: Every time \u002F Intermittent since [date]\n```\n\n## Resources\n\n- [Notion API Reference](https:\u002F\u002Fdevelopers.notion.com\u002Freference\u002Fintro)\n- [Notion Status Page](https:\u002F\u002Fstatus.notion.com)\n- [Property Value Types](https:\u002F\u002Fdevelopers.notion.com\u002Freference\u002Fproperty-value-object)\n- [Block Types](https:\u002F\u002Fdevelopers.notion.com\u002Freference\u002Fblock)\n- [GitHub: notion-sdk-js Issues](https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-sdk-js\u002Fissues)\n\n## Next Steps\n\nFor load testing and scaling, see `notion-load-scale`.\nFor reliability patterns, see `notion-reliability-patterns`.\n","# Notion Advanced Troubleshooting\n\n## Overview\n\nDeep debugging techniques for Notion API issues that resist standard fixes. Covers API response inspection with request IDs, permission chain tracing through page hierarchies, property type mismatch detection against database schemas, pagination edge cases with cursor validation, and block nesting limit violations (max depth of 3 levels via API). Uses `Client` from `@notionhq\u002Fclient` and raw `curl` for comparison testing.\n\n## Prerequisites\n\n- `@notionhq\u002Fclient` v2.x installed (`npm install @notionhq\u002Fclient`)\n- Python: `notion-client` installed (`pip install notion-client`)\n- `curl` available for raw API testing\n- `NOTION_TOKEN` environment variable set (internal integration token starting with `ntn_`)\n- Pages\u002Fdatabases shared with your integration via Notion UI\n\n## Instructions\n\n### Step 1: API Response Inspection with Request ID Tracking\n\nEvery Notion API response includes an `x-request-id` header. Capture it for debugging and support tickets.\n\n```typescript\nimport { Client, LogLevel, isNotionClientError, APIErrorCode } from '@notionhq\u002Fclient';\n\nconst notion = new Client({\n  auth: process.env.NOTION_TOKEN,\n  logLevel: LogLevel.DEBUG, \u002F\u002F Logs full request\u002Fresponse to stderr\n});\n\n\u002F\u002F Wrapper that captures request ID and timing for every call\nasync function tracedCall\u003CT>(\n  label: string,\n  fn: () => Promise\u003CT>\n): Promise\u003C{ result: T; durationMs: number }> {\n  const start = Date.now();\n  try {\n    const result = await fn();\n    const durationMs = Date.now() - start;\n    console.log(`[${label}] OK ${durationMs}ms`);\n    return { result, durationMs };\n  } catch (error) {\n    const durationMs = Date.now() - start;\n    if (isNotionClientError(error)) {\n      console.error(`[${label}] FAILED ${durationMs}ms`, {\n        code: error.code,\n        status: error.status,\n        message: error.message,\n        body: error.body,\n      });\n    }\n    throw error;\n  }\n}\n\n\u002F\u002F Compare SDK vs raw curl to isolate SDK issues\n\u002F\u002F Run in bash alongside:\n\u002F\u002F curl -v https:\u002F\u002Fapi.notion.com\u002Fv1\u002Fpages\u002FPAGE_ID \\\n\u002F\u002F   -H \"Authorization: Bearer $NOTION_TOKEN\" \\\n\u002F\u002F   -H \"Notion-Version: 2022-06-28\" 2>&1 | grep x-request-id\n```\n\n```python\nfrom notion_client import Client\nimport logging\n\n# Enable debug logging for full request\u002Fresponse visibility\nlogging.basicConfig(level=logging.DEBUG)\nnotion = Client(auth=os.environ[\"NOTION_TOKEN\"], log_level=logging.DEBUG)\n\n# Traced wrapper for Python\nimport time\n\ndef traced_call(label: str, fn):\n    start = time.time()\n    try:\n        result = fn()\n        duration = (time.time() - start) * 1000\n        print(f\"[{label}] OK {duration:.0f}ms\")\n        return result\n    except Exception as e:\n        duration = (time.time() - start) * 1000\n        print(f\"[{label}] FAILED {duration:.0f}ms: {e}\")\n        raise\n```\n\n### Step 2: Permission Chain Tracing\n\nWhen you get `object_not_found` (404), the page exists but your integration lacks access. Trace the permission chain up the page hierarchy.\n\n```typescript\nasync function tracePermissionChain(pageId: string): Promise\u003Cvoid> {\n  console.log(`\\n=== Permission Chain Trace for ${pageId} ===`);\n  let currentId = pageId;\n  let depth = 0;\n\n  while (currentId && depth \u003C 10) {\n    try {\n      const page = await notion.pages.retrieve({ page_id: currentId });\n      const parent = (page as any).parent;\n      console.log(`  ${'  '.repeat(depth)}[${depth}] Page ${currentId} - ACCESSIBLE`);\n      console.log(`  ${'  '.repeat(depth)}    Parent type: ${parent.type}`);\n\n      if (parent.type === 'database_id') {\n        \u002F\u002F Check database access too\n        try {\n          await notion.databases.retrieve({ database_id: parent.database_id });\n          console.log(`  ${'  '.repeat(depth)}    Database ${parent.database_id} - ACCESSIBLE`);\n        } catch {\n          console.log(`  ${'  '.repeat(depth)}    Database ${parent.database_id} - NO ACCESS`);\n        }\n        break;\n      } else if (parent.type === 'page_id') {\n        currentId = parent.page_id;\n      } else if (parent.type === 'workspace') {\n        console.log(`  ${'  '.repeat(depth)}    Root: workspace`);\n        break;\n      } else {\n        break;\n      }\n      depth++;\n    } catch (error) {\n      if (isNotionClientError(error) && error.code === APIErrorCode.ObjectNotFound) {\n        console.log(`  ${'  '.repeat(depth)}[${depth}] Page ${currentId} - NO ACCESS (object_not_found)`);\n        console.log(`  ${'  '.repeat(depth)}    Fix: Open this page in Notion → ··· → Connections → Add your integration`);\n      } else {\n        console.log(`  ${'  '.repeat(depth)}[${depth}] Page ${currentId} - ERROR: ${(error as Error).message}`);\n      }\n      break;\n    }\n  }\n}\n\n\u002F\u002F Also verify bot identity and capabilities\nconst me = await notion.users.me({});\nconsole.log('Bot user:', me.name, '| Type:', me.type);\n\u002F\u002F If me.type !== 'bot', your token is wrong\n```\n\n```python\ndef trace_permission_chain(page_id: str):\n    \"\"\"Walk up the page hierarchy to find where access breaks.\"\"\"\n    current_id = page_id\n    depth = 0\n\n    while current_id and depth \u003C 10:\n        try:\n            page = notion.pages.retrieve(page_id=current_id)\n            parent = page[\"parent\"]\n            print(f\"  [depth={depth}] {current_id} - ACCESSIBLE (parent: {parent['type']})\")\n\n            if parent[\"type\"] == \"database_id\":\n                try:\n                    notion.databases.retrieve(database_id=parent[\"database_id\"])\n                    print(f\"  [depth={depth}] Database {parent['database_id']} - ACCESSIBLE\")\n                except Exception:\n                    print(f\"  [depth={depth}] Database {parent['database_id']} - NO ACCESS\")\n                break\n            elif parent[\"type\"] == \"page_id\":\n                current_id = parent[\"page_id\"]\n            else:\n                break\n            depth += 1\n        except Exception as e:\n            print(f\"  [depth={depth}] {current_id} - NO ACCESS: {e}\")\n            print(f\"  Fix: Share this page with your integration in Notion UI\")\n            break\n```\n\n### Step 3: Property Type Mismatch Detection and Pagination Edge Cases\n\nThe most common `validation_error` comes from sending the wrong property type. Validate against the live schema before creating\u002Fupdating.\n\n```typescript\n\u002F\u002F Detect property type mismatches against live database schema\nasync function detectPropertyMismatches(\n  databaseId: string,\n  properties: Record\u003Cstring, unknown>\n): Promise\u003Cstring[]> {\n  const db = await notion.databases.retrieve({ database_id: databaseId });\n  const schema = db.properties;\n  const issues: string[] = [];\n\n  \u002F\u002F Check each property you're trying to set\n  for (const [name, value] of Object.entries(properties)) {\n    if (!schema[name]) {\n      issues.push(\n        `Property \"${name}\" not found. Available: ${Object.keys(schema).join(', ')}`\n      );\n      continue;\n    }\n\n    const expectedType = schema[name].type;\n    const sentType = Object.keys(value as object).find(k =>\n      ['title', 'rich_text', 'number', 'select', 'multi_select',\n       'date', 'checkbox', 'url', 'email', 'phone_number',\n       'people', 'relation', 'files', 'status'].includes(k)\n    );\n\n    if (sentType && sentType !== expectedType) {\n      issues.push(\n        `\"${name}\": schema type is \"${expectedType}\" but you sent \"${sentType}\"`\n      );\n    }\n  }\n\n  \u002F\u002F Check for missing title property (required for page creation)\n  const titleProp = Object.entries(schema).find(([, v]) => v.type === 'title');\n  if (titleProp && !properties[titleProp[0]]) {\n    issues.push(`Missing required title property \"${titleProp[0]}\"`);\n  }\n\n  return issues;\n}\n\n\u002F\u002F Pagination edge cases: cursor validation and empty page handling\nasync function safeFullPagination(databaseId: string, filter?: any) {\n  const allResults: any[] = [];\n  let cursor: string | undefined;\n  let pageCount = 0;\n  const MAX_PAGES = 1000; \u002F\u002F Safety valve: 100K records max\n\n  do {\n    if (pageCount >= MAX_PAGES) {\n      console.warn(`Pagination safety limit reached (${MAX_PAGES} pages, ${allResults.length} results)`);\n      break;\n    }\n\n    const response = await notion.databases.query({\n      database_id: databaseId,\n      filter,\n      page_size: 100,\n      start_cursor: cursor,\n    });\n\n    allResults.push(...response.results);\n    pageCount++;\n\n    \u002F\u002F Edge case: has_more is true but next_cursor is null (API bug, rare)\n    if (response.has_more && !response.next_cursor) {\n      console.warn('Pagination anomaly: has_more=true but next_cursor is null');\n      break;\n    }\n\n    cursor = response.has_more ? (response.next_cursor ?? undefined) : undefined;\n\n    \u002F\u002F Rate limit compliance: ~3 req\u002Fs\n    await new Promise(r => setTimeout(r, 350));\n  } while (cursor);\n\n  console.log(`Paginated ${pageCount} pages, ${allResults.length} total results`);\n  return allResults;\n}\n\n\u002F\u002F Block nesting limit detection\n\u002F\u002F Notion API allows max 3 levels of nested blocks (API limitation)\n\u002F\u002F UI supports deeper nesting, but API cannot create\u002Fread beyond depth 3\nasync function checkBlockNesting(blockId: string, depth = 0): Promise\u003Cnumber> {\n  if (depth >= 3) {\n    console.warn(`Block nesting limit reached at depth ${depth} (API max is 3)`);\n    return depth;\n  }\n\n  const children = await notion.blocks.children.list({ block_id: blockId });\n  let maxDepth = depth;\n\n  for (const block of children.results) {\n    if ((block as any).has_children) {\n      const childDepth = await checkBlockNesting((block as any).id, depth + 1);\n      maxDepth = Math.max(maxDepth, childDepth);\n    }\n  }\n\n  return maxDepth;\n}\n```\n\n```python\ndef detect_property_mismatches(database_id: str, properties: dict) -> list[str]:\n    \"\"\"Validate properties against live database schema.\"\"\"\n    db = notion.databases.retrieve(database_id=database_id)\n    schema = db[\"properties\"]\n    issues = []\n\n    for name, value in properties.items():\n        if name not in schema:\n            available = \", \".join(schema.keys())\n            issues.append(f'Property \"{name}\" not found. Available: {available}')\n            continue\n\n        expected_type = schema[name][\"type\"]\n        sent_types = [k for k in value.keys() if k in\n            (\"title\", \"rich_text\", \"number\", \"select\", \"multi_select\",\n             \"date\", \"checkbox\", \"url\", \"email\", \"status\")]\n        if sent_types and sent_types[0] != expected_type:\n            issues.append(f'\"{name}\": expected \"{expected_type}\", got \"{sent_types[0]}\"')\n\n    # Check for missing title\n    title_props = [k for k, v in schema.items() if v[\"type\"] == \"title\"]\n    if title_props and title_props[0] not in properties:\n        issues.append(f'Missing required title property \"{title_props[0]}\"')\n\n    return issues\n```\n\n## Output\n\n- Request IDs captured for every API call with timing data\n- Permission chain traced from target page up to workspace root\n- Property type mismatches detected before they cause validation errors\n- Pagination edge cases handled (null cursors, safety limits)\n- Block nesting depth verified against API 3-level limit\n\n## Error Handling\n\n| Symptom | Root Cause | Debug Approach |\n|---------|-----------|----------------|\n| `object_not_found` on valid page | Page not shared with integration | Run `tracePermissionChain()` |\n| `validation_error` on create\u002Fupdate | Property type mismatch | Run `detectPropertyMismatches()` |\n| Missing data from query | Not paginating (max 100\u002Frequest) | Use `safeFullPagination()` |\n| `could not find block` at depth 4+ | API nesting limit (3 levels) | Flatten block structure |\n| Works in curl, fails in SDK | SDK header or payload difference | Enable `LogLevel.DEBUG`, compare |\n| Intermittent 500 errors | Notion server issues | Capture `x-request-id`, retry with backoff |\n| `rate_limited` (429) | Exceeding 3 req\u002Fs | Add 350ms delay between calls |\n| `conflict_error` | Concurrent page update | Retry with fresh page read |\n\n## Examples\n\n### Minimal Reproduction Script\n\n```typescript\n\u002F\u002F Strip to bare minimum to isolate the issue\nasync function minimalRepro() {\n  const notion = new Client({\n    auth: process.env.NOTION_TOKEN,\n    logLevel: LogLevel.DEBUG,\n  });\n\n  \u002F\u002F 1. Auth check\n  const me = await notion.users.me({});\n  console.log('Auth OK:', me.name);\n\n  \u002F\u002F 2. Search check (proves token works)\n  const search = await notion.search({ page_size: 1 });\n  console.log('Search OK:', search.results.length, 'results');\n\n  \u002F\u002F 3. Specific resource check\n  const db = await notion.databases.retrieve({\n    database_id: process.env.NOTION_DB_ID!,\n  });\n  console.log('DB OK:', Object.keys(db.properties).join(', '));\n\n  \u002F\u002F 4. The failing operation — insert exact failing call here\n}\n\nminimalRepro().catch(console.error);\n```\n\n### Support Escalation Template\n\n```\nSubject: [Request ID: abc123] validation_error on pages.create\nEnvironment: Node.js 20, @notionhq\u002Fclient 2.2.15, API 2022-06-28\nIntegration ID: [from notion.so\u002Fprofile\u002Fintegrations]\nRequest ID: [from x-request-id header or error body]\nTimestamp: 2026-03-22T14:30:00Z\n\nSteps: POST \u002Fv1\u002Fpages with body: { ... }\nExpected: 200 with page object\nActual: 400 validation_error \"...\"\nFrequency: Every time \u002F Intermittent since [date]\n```\n\n## Resources\n\n- [Notion API Reference](https:\u002F\u002Fdevelopers.notion.com\u002Freference\u002Fintro)\n- [Notion Status Page](https:\u002F\u002Fstatus.notion.com)\n- [Property Value Types](https:\u002F\u002Fdevelopers.notion.com\u002Freference\u002Fproperty-value-object)\n- [Block Types](https:\u002F\u002Fdevelopers.notion.com\u002Freference\u002Fblock)\n- [GitHub: notion-sdk-js Issues](https:\u002F\u002Fgithub.com\u002Fmakenotion\u002Fnotion-sdk-js\u002Fissues)\n\n## Next Steps\n\nFor load testing and scaling, see `notion-load-scale`.\nFor reliability patterns, see `notion-reliability-patterns`.\n",{"name":5,"tags":24,"author":28,"license":15,"version":29,"description":30,"allowed-tools":31,"compatible-with":32},[25,26,27],"saas","productivity","notion","Jeremy Longshore \u003Cjeremy@intentsolutions.io>","1.0.0","Deep debugging for Notion API: response inspection, permission chain tracing,\nproperty type mismatches, pagination edge cases, and block nesting limits.\nUse when standard troubleshooting fails or investigating intermittent errors.\nTrigger with phrases like \"notion deep debug\", \"notion permission trace\",\n\"notion property mismatch\", \"notion pagination bug\", \"notion nesting limit\".\n","Read, Grep, Bash(curl:*), Bash(node:*)","claude-code","main","99825ad3f3bcc6597ddcc7294a14e6e922f2b67b","skills\u002Fsaas-packs--notion-pack--notion-advanced-troubleshooting",0,"https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills","https:\u002F\u002Fgithub.com\u002Fjukeyman","https:\u002F\u002FRJBUSINESSSOLUTIONS.ORG","Credit and Finance Expert | Developer\r\n\r\nI'm Rick Jefferson, a seasoned credit and finance expert with over a decade of experience in financial literacy,","2026-07-13 07:03:29",{"source":8,"skillName":5,"commands":43,"prompt":53,"zipAvailable":54},[44,47,50],{"tool":45,"command":46},"npx","npx skills add jukeyman\u002Fjukeyman-skills --skill notion-advanced-troubleshooting",{"tool":48,"command":49},"bunx","bunx skills add jukeyman\u002Fjukeyman-skills --skill notion-advanced-troubleshooting",{"tool":51,"command":52},"pnpm","pnpm dlx skills add jukeyman\u002Fjukeyman-skills --skill notion-advanced-troubleshooting","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fsaas-packs--notion-pack--notion-advanced-troubleshooting\u002FSKILL.md",true,[],[57,64,71,78,85,93],{"skillNo":58,"name":59,"nameZh":6,"description":60,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":61,"categories":62,"keywords":63,"publishedAt":19},"01M79ANS2SM329NEP5ZCX106RR","zustand-store-creator","Create zustand store creator operations. Auto-activating skill for Frontend Development.\nTriggers on: zustand store creator, zustand store creator\nPart of the Frontend Development skill category. Use when working with zustand store creator functionality. Trigger with phrases like \"zustand store creator\", \"zustand creator\", \"zustand\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzustand-store-creator\u002FSKILL.md",[],[],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":19},"01M79AMZKP4YDEZ7EHG1Y7PP74","zero-trust-config-helper","Configure with zero trust config helper operations. Auto-activating skill for Security Advanced.\nTriggers on: zero trust config helper, zero trust config helper\nPart of the Security Advanced skill category. Use when configuring systems or services. Trigger with phrases like \"zero trust config helper\", \"zero helper\", \"zero\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzero-trust-config-helper\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M79AMJSBCEJQNBTYNAHYN5HM","zapier-integration-helper","Assist with zapier integration helper operations. Auto-activating skill for Business Automation.\nTriggers on: zapier integration helper, zapier integration helper\nPart of the Business Automation skill category. Use when working with APIs or building integrations. Trigger with phrases like \"zapier integration helper\", \"zapier helper\", \"zapier\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzapier-integration-helper\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M79AHJZGVMARS13VFQYRR1MP","yaml-config-validator","Validate yaml config validator operations. Auto-activating skill for DevOps Basics.\nTriggers on: yaml config validator, yaml config validator\nPart of the DevOps Basics skill category. Use when configuring systems or services. Trigger with phrases like \"yaml config validator\", \"yaml validator\", \"yaml\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fyaml-config-validator\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":89,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":19},"01M79AHGDZRN0020RDQSQDPAM8","xvary-stock-research","Thesis-driven equity analysis from public SEC EDGAR and market data; \u002Fanalyze, \u002Fscore, \u002Fcompare workflows with bundled Python tools (Claude Code, Cursor, Codex).","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fxvary-stock-research\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fxvary-stock-research\u002FSKILL.md",[],[],{"skillNo":94,"name":95,"nameZh":6,"description":96,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":97,"categories":98,"keywords":99,"publishedAt":19},"01M79AHCYJ9FV9RMHQ24HDRN33","xss-vulnerability-scanner","Scan xss vulnerability scanner operations. Auto-activating skill for Security Fundamentals.\nTriggers on: xss vulnerability scanner, xss vulnerability scanner\nPart of the Security Fundamentals skill category. Use when working with xss vulnerability scanner functionality. Trigger with phrases like \"xss vulnerability scanner\", \"xss scanner\", \"xss\".","https:\u002F\u002Fgithub.com\u002Fjukeyman\u002Fjukeyman-skills\u002Fblob\u002Fmain\u002Fskills\u002Fxss-vulnerability-scanner\u002FSKILL.md",[],[]]