Troubleshooting

Connection issues

”Connection failed” or 401 error (manual token)

Your integration token is invalid, expired, or has extra spaces.

Go to notion.so/my-integrations and verify your integration exists.
Copy the token again - it starts with ntn_. No leading or trailing spaces.
Paste it into N2O Settings > Connection > Manual Connection > Notion API Token.
Click Connect to Notion. A token Notion rejects says so on the spot.

OAuth connection failed

In N2O Settings > Connection > OAuth Connection, click Disconnect, then Connect to Notion. That opens the N2O panel, which is where the sign-in happens.
Complete the Notion authorization flow in your browser.
If Obsidian doesn’t open automatically after authorization, check that Obsidian is running and try again.

Pages not accessible despite valid token (manual token only)

Notion integrations can only access pages explicitly shared with them.

Open the Notion page or database.
Click ”…” > Connections > Connect to > select your integration.
Sharing a database shares all items inside it. Sharing a parent page shares its children.

Rate limiting (429 errors)

Notion’s documented limit is an average of 3 requests per second. N2O runs a token bucket at that rate with a burst of 60, so a small sync finishes at full speed and a large one settles down to the sustained rate. A very large workspace can still be throttled by Notion, and N2O waits it out rather than failing.

N2O retries on 429 errors automatically with backoff - you don’t need to do anything.
If it happens frequently, narrow what you sync or raise the full re-scan interval to 15+ hours.

Sync not starting

Nothing happens when triggering a sync

Check the plugin is enabled in Settings > Community Plugins.
Check that a Notion token or OAuth connection is configured.
Look at the status bar - if it says “Syncing…”, a sync is already in progress.
Open the developer console (Ctrl+Shift+I / Cmd+Option+I) and look for error messages.

”Database not initialized” error

The sql-wasm.wasm file is missing from the plugin directory.

Check that sql-wasm.wasm exists at .obsidian/plugins/n2o/sql-wasm.wasm.
If missing, reinstall the plugin.
Restart Obsidian.

”0 items synced” - sync completes instantly

You haven’t selected any pages yet.

Open N2O Settings > Sync > Pick from Notion.
Click Pick from Notion to open the picker.
Select the databases or pages you want to sync.
Run Sync again.

Missing pages

A specific page doesn’t appear after sync

The page isn’t shared with your integration (manual token only). Open the page in Notion > ”…” > Connections > connect your integration.

With OAuth, all pages you authorized during setup should be accessible. If a page is still missing, re-authorize: N2O Settings > Connection > OAuth Connection, Disconnect, then Connect to Notion.

Only some database items sync

Two common causes:

Database filters are active. Open N2O Settings > Sync > Pick from Notion, select the database in the picker, and click its Filters button to check for active conditions.
Page limit reached. The free 14-day trial syncs up to 300 pages. Upgrade to Pro or Lifetime to remove the cap.

Pages disappear into `_orphaned/`

Pages moved to _orphaned/ were in sync state but no longer found in Notion - either deleted, moved outside what you sync, or no longer shared with your integration.

If the page still exists in Notion, re-share it with your integration and run sync.
Files in _orphaned/ are normal Markdown - move them back manually if needed.
Their notion_id frontmatter is preserved so N2O can re-link them on the next sync.

Duplicate files

Files with a “(1)” suffix appearing

This happens when N2O writes a file where one already exists but isn’t tracked in sync state - usually after a reset or state recovery.

Open both files and check notion_id in their frontmatter.
Delete the one without a notion_id, or the older one.
The next sync will stabilize - N2O recovers sync state from frontmatter automatically.

Media not downloading

Images show as broken links

Notion’s S3 URLs expire after ~1 hour. If downloads failed during sync, run sync again - N2O retries failed media with fresh URLs automatically.

Also check that Download Media is enabled in N2O Settings > Sync > Media.

Large files fail to download

Downloads time out after 120 seconds. Files over 50 MB log a warning.

Retry sync - transient network failures usually resolve.
If a specific file consistently fails, download it manually and place it in the _files/ folder using the expected filename format ({name}-{8-char-hash}.{ext}).

Sending edits to Notion

Sending shows 0 changes

Trial expired? Sending edits needs an active license. Sync works during the free 14-day trial and on any paid plan; after the trial it pauses until you start Pro or Lifetime.
Files outside sync folder? Only files inside your configured sync folder are scanned.
No changes since the last send? N2O uses content hashes - if the file content hasn’t changed since it last went up successfully, it’s skipped.
Enable debug mode and check the developer console to see exactly what the change detector finds.

”No Notion ID” - can’t send a note

Notes without a notion_id in frontmatter aren’t linked to Notion. Options:

Run Sync first - if the page exists in Notion, the note will get a notion_id.
Use “N2O Sync: Send this note to Notion” from the command palette. If the note has no notion_id yet, that command creates the Notion page and writes the ID back.

”Push aborted - sync state appears empty”

This safety guard fires after a database reset. Run N2O: Sync with Notion first to re-establish sync state, then send your edits again.

Enhanced Metadata issues

Linked views show all items instead of filtered subset

Check N2O Settings > Sync > Include all items from linked views. On, that toggle deliberately syncs the whole source database and ignores each view’s filter. Turn it off to sync only what the view shows.

Enhanced Metadata is not the answer here. Linked view resolution and filter detection run on the official Notion API, so turning it on does not change what a linked view brings in.

”Token invalid or expired” in Enhanced Metadata

The token_v2 cookie expires when that Notion session ends. N2O reads it from Obsidian’s own Web Viewer, not from Chrome or Safari, so re-grab it there:

In N2O Settings > Notionify > Enhanced metadata, click Sign in to Notion and log in inside Obsidian’s Web Viewer.
Come back to the same panel and click Grab Token again.

Performance

First sync is slow

Expected - the first sync fetches everything. The first 60 requests spend the burst and go at full speed, then it settles to 3 per second, so 500 pages takes a couple of minutes. Subsequent syncs are incremental and much faster. Use selective sync to reduce first-sync scope.

Plugin takes a few seconds to load

N2O loads a ~1 MB WebAssembly binary (sql.js) on startup. This takes 1-3 seconds and only happens once per Obsidian launch.

Database corruption

Automatic recovery

If the SQLite database becomes corrupt (crash, cloud sync conflict on the data file), N2O handles it automatically:

Backs up the corrupt file as n2o.db.corrupt.
Creates a fresh database.
Recovers sync state from vault frontmatter on the next sync.

No action required. The first sync after recovery will be a full sync.

Manual reset

In N2O Settings > Advanced, click Reset N2O to clear all sync records. Your vault files are never deleted by a reset.

General tips

Enable debug mode

N2O Settings > Advanced > Debug Mode enables detailed logging in the developer console (Ctrl+Shift+I / Cmd+Option+I). Always enable this before reporting a bug.

Start again from the panel

If your configuration is in a bad state, open N2O Settings > Connection and click Open Dashboard in the Setup row at the bottom, or run N2O Sync: Open N2O panel from the Command Palette. The panel is where connecting, picking what to sync and running a sync all live, so it is the one surface to work from. Reconnecting Notion is on the same Connection tab, under OAuth Connection and Manual Connection.

Getting help

Enable debug mode and reproduce the problem.
Copy the relevant log output from the developer console.
Note your N2O version, Obsidian version, operating system, and plan (Trial/Pro/Lifetime).
Report the issue at github.com/n2osync/n2o/issues or email support@n2osync.com.