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, reduce sync scope or increase auto-sync interval to 15+ minutes.

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 Sync Configuration from N2O Settings or the Dashboard.
Go to Content & Folders > What to Sync.
If set to “Selected”, click Choose Pages and select databases or pages.
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 Sync Configuration > Database Configuration, find the database, and check for filter conditions.
Free tier limit. Free tier syncs up to 100 pages. Upgrade to Pro or start a 14-day trial for unlimited.

Pages disappear into `_orphaned/`

Pages moved to _orphaned/ were in sync state but no longer found in Notion — either deleted, moved outside your sync scope, 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 Sync Configuration > Sync Behavior.

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}).

Push sync issues

Push shows 0 changes

Free tier? Push sync requires Pro or an active trial.
Files outside sync folder? Only files inside your configured sync folder are scanned.
No changes since last push? N2O uses content hashes — if the file content hasn’t changed since the last successful push, it’s skipped.
Enable debug mode and check the developer console to see exactly what the change detector finds.

”No Notion ID” — can’t push a file

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

Run pull sync first — if the page exists in Notion, it will get a notion_id.
Use “N2O: Create current file 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 Sync with Notion (merge) first to re-establish sync state, then push 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 > 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 > 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, scope selection, 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 tier (Free/Trial/Pro).
Report the issue at github.com/n2osync/n2o/issues or email support@n2osync.com.