Skip to content

Troubleshooting

Jump to bottom
Brandon Young edited this page Nov 5, 2026 · 1 revision

Troubleshooting

Start with:

notion-md-sync verify
notion-md-sync <command> --verbose

notion.token is required / notion.parent_page_id is required

The settings weren't found. Check that:

  • NOTION_MD_SYNC_NOTION_TOKEN and NOTION_MD_SYNC_NOTION_PARENT_PAGE_ID are set, or a .env with them is in the current folder, ~/.notion-md-sync/, or up to three folders above.
  • Your config.yaml is somewhere the tool looks: ./config.yaml, ./configs/config.yaml or ~/.notion-md-sync/config.yaml. Anywhere else, pass -c path/to/config.yaml. The repo's config/ folder is not searched.

See Configuration.

init fails or hangs

init reads answers from the terminal, so it fails when stdin isn't interactive (CI, scripts, some IDE consoles). It also ignores NOTION_MD_SYNC_NOTION_TOKEN and always asks for the token. In those cases, write config.yaml and .env by hand (Configuration).

401, 403 or 404 from Notion

  • Share the parent page with your integration (••• → Connections).
  • Check the page ID: it's the 32-character hex string at the end of the page URL.
  • Check that the token is current. Tokens start with ntn_, or secret_ for older ones.

push: accepts at most 1 arg(s), received N

push takes zero or one file. For several files:

notion-md-sync add a.md b.md c.md
notion-md-sync push

Or push everything under the root with notion-md-sync sync push.

A file isn't syncing

  • Its frontmatter may have sync_enabled: false.
  • It may match excluded_patterns, sit in a hidden folder, or be outside markdown_root.
  • push with no argument only pushes staged files. Check notion-md-sync status.

My edits to a block didn't reach Notion

Text between <!-- notion:TYPE ID begin --> and <!-- notion:end ... --> is a read-only copy of a block Markdown can't express. Edit that block in Notion. See Directory Layout and Kept Blocks.

"Not renaming … the page changed in Notion since the last sync"

You changed title in the frontmatter, and someone also edited the page in Notion. Pull first, then change the title again.

Edits to a CSV file don't show up in Notion

Databases are exported on pull only. See Databases.

Sub-pages are missing after pull

  • The integration needs access to every sub-page. Pages that were shared separately, or moved in from elsewhere, may not inherit access.
  • Run with --verbose to see which pages were found.

A long pull stops early

Commands stop after --timeout (default 30m). Raise it for very large workspaces:

notion-md-sync pull --timeout 2h

Conflicts during sync bidirectional

What happens depends on sync.conflict_resolution. With diff (the default), or with newer when a timestamp is missing, you're shown both versions and asked to choose. That needs an interactive terminal. In scripts, set notion_wins or markdown_wins instead.

Getting help

notion-md-sync

Clone this wiki locally