Troubleshooting Teams “Wiki” to “OneNote” Migration Sync Errors

When Microsoft Teams channels migrate legacy channel Wikis to OneNote (Teams Notes), users frequently encounter synchronization failures, missing pages, or errors stating “We couldn’t export your wiki to Notes.” These failures occur when the automated migration pipeline cannot parse legacy Wiki formatting, hits SharePoint permissions blocks, or exceeds OneNote notebook character limits.

Fast Fix

Open the Teams channel’s Files tab and select Open in SharePoint. Locate the Teams Site Assets library to confirm whether the target notebook file exists. If the automated exporter fails repeatedly, copy the raw markdown text directly out of the legacy Wiki tab and paste it into the channel’s modern Notes tab manually.

---

Diagnostic Snapshot

Symptom	Root Cause	Escalation Point
“Export to Notes failed”	Site collection permissions or disabled OneNote provisioning	Team Owner / SharePoint Admin
Missing Images/Attachments	Inline image links in Wiki pointing to broken local references	End User (Manual Re-upload)
“OneNote cannot sync section”	Illegal characters in Wiki page title	Team Owner (Rename Page)
Infinite Migration Loop	Orphaned Wiki data lock in SharePoint backend	Microsoft 365 Admin

---

Why the Wiki-to-OneNote Migration Fails

The legacy Teams Wiki used a specialized database framework stored directly inside hidden SharePoint document libraries under Teams Wiki Data. The modern replacement, OneNote, uses an entirely different file architecture hosted inside the site’s Site Assets library.

[Legacy Teams Wiki] ──> Stored in hidden 'Teams Wiki Data' folder
                             │
                             ▼  (Automated Migration Tool)
[OneNote Notebook]  ──> Stored in 'Site Assets/[Team Name] Notebook'

The migration engine encounters hard synchronization breaks during this conversion because:

1. Title and Character Rule Conflicts: Teams Wiki allowed page names containing characters such as ?, , :, |, and /. OneNote section titles strictly forbid these characters. If a Wiki page title violates OneNote naming rules, the automated migration tool halts.
2. Library Permissions and Locking: The target OneNote notebook must inherit write permissions from the SharePoint site collection. If the Site Assets library has broken inheritance or is restricted, the export tool cannot create new OneNote sections.
3. Large Inline Assets: Teams Wiki supported large inline images and attachments stored in base64 strings or direct subfolder links. The exporter often times out when transferring attachments larger than standard API call thresholds.

If the OneNote app itself is throwing licensing or access prompts after the export finishes, review “We can’t get to your notebooks” OneNote Activation Error.

---

Progressive Troubleshooting Steps

1. Audit and Clean Forbidden Characters in Wiki Page Titles

The most frequent cause of export sync failure is a special character in the title of a Wiki tab, section, or page.

1. Open the original Wiki tab in the problem Teams channel.
2. Review every section header and subpage title in the navigation pane.
3. Remove any of the following characters from all titles: \ / : * ? " < > |
4. Verify that no page titles exceed 50 characters, and ensure no titles end with a period (.) or trailing space.
5. Once renamed, retry the export process by clicking Export to Notes.

2. Confirm Site Assets Permissions and Storage Space

The export process writes directly to the SharePoint site collection that supports the Team. If that site is read-only or out of space, the export fails instantly.

1. In the Teams channel, go to the Files tab and click Open in SharePoint.
2. In the top-right corner, check whether the site displays a read-only banner or quota warning. If the site is locked due to storage limits, review “The site is read-only because it’s full” SharePoint Error.
3. On the left navigation pane, click Site contents.
4. Open the Site Assets library.
5. Click the Settings gear > Library settings > More library settings.
6. Select Permissions for this document library and verify that [Team Name] Members has Edit access. If permissions are broken or set to Read, restore inheritance.

If permissions to site files are generally inaccessible for team members, resolve those underlying group links using “Access Denied” to Teams Files despite being Team Member.

3. Resolve Missing Inline Media and Broken Links

If the text exports successfully but images display as red “X” icons or broken image links inside the new Notes tab:

1. The automated migration pipeline occasionally loses track of asset paths stored in the old Teams Wiki Data library.
2. In SharePoint Site contents, open the folder named Teams Wiki Data.
3. Locate the subfolder corresponding to the channel name. Inside, you will find the original raw image assets (.png, .jpg) that were pasted into the Wiki.
4. Download the missing images to your local drive.
5. In Teams, open the Notes tab, navigate to the relevant page, and use Insert > Picture to re-embed the files directly into OneNote.

If you encounter general file link breaks across SharePoint pages during this restructuring, consult How to Fix “Broken Links” in SharePoint Document Libraries.

4. Fallback: Manual Migration via Web Interface

If the automated export tool throws an unhandled error and refuses to run, execute a manual migration to recover your data without administrative intervention.

1. Open the Wiki tab in Teams.
2. Click inside the content pane, press Ctrl + A, and copy the text (Ctrl + C).
3. Click the + (Add a tab) button at the top of the channel and select OneNote.
4. Select the default Team notebook, or choose Create new notebook.
5. Create a new section named after your channel, create a page, and paste the content (Ctrl + V).
6. Once the manual transfer is confirmed, right-click the old Wiki tab and select Remove to clean up the interface.

---

Hard Stops: When to Escalate to a Global Administrator

If the automated migration fails with an explicit code indicating API failures, or if the Teams Wiki Data folder is missing entirely despite the Wiki tab functioning in Teams, stop attempting client-side exports.

An administrator must verify:

• Graph API Throttling: Rapid, large-scale migrations across many channels can trigger SharePoint API throttling. Check Troubleshooting “Throttling” Errors (429) in SharePoint Large Libraries.
• Purview Retention Policies: If a compliance retention lock is applied to the site, hidden system folders (like Wiki data directories) cannot be updated or converted. A compliance administrator must grant an exclusion before migration can complete.