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 > Notion API Token.
Click Test Connection.

OAuth connection failed

Click Reconnect in N2O Settings > Connection.
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 enforces 3 requests per second. N2O targets 2.5 req/s but large workspaces can still trigger throttling.

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 > What to sync.
Click Choose items 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 via N2O Settings > Connection > Reconnect.

Only some database items sync

Two common causes:

Database filters are active. Open N2O Settings > Sync > What to sync, 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 60 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: Create this note in Notion” from the command palette to create it in Notion and get an ID.

”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

Enhanced Metadata is not enabled or the session token has expired.

Open N2O Settings > Notionify > Enhanced metadata.
Toggle Enable Enhanced Metadata on.
Click Grab Token (or enter your token_v2 cookie manually).
Click Validate to confirm it works.

See Enhanced Metadata for the full setup guide.

”Token invalid or expired” in Enhanced Metadata

The token_v2 cookie expires when you log out of Notion in your browser. Re-grab it:

Log in to notion.so in your browser.
In N2O Settings > Notionify > Enhanced metadata, click Grab Token again.

Performance

First sync is slow

Expected - the first sync fetches everything. At Notion’s rate limit (2.5 req/s), 500 pages takes several minutes minimum. 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.

Run the Setup Wizard

If your configuration is in a bad state, open N2O Settings > Connection and click Setup Wizard. It walks through token/OAuth, choosing what to sync, and folder setup.

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.