[YifengMao]

Why

A missing file referenced by an embedded-document web part currently aborts page migration: DocumentEmbedLookup returns null, so subsequent mapping functions fail because DocumentAuthor and other metadata properties are undefined. An already-broken embed should not prevent the rest of the page from migrating.

Approach

• Return the complete five-property metadata contract with empty values when SharePoint reports System.IO.FileNotFoundException, rather than returning null.
• Preserve the original document URL through the existing mappings. No XML mapping changes are needed.
• Emit a warning containing the referenced path and lookup context, explain that migration continues, and recommend checking the URL, document existence, and migration identity's access.
• Apply the same file-not-found warning/fallback during hosting-web discovery.
• Preserve successful lookups and propagation of explicit access-denied and unexpected server errors during document retrieval. Existing non-file-not-found hosting-web-discovery error handling is otherwise unchanged.
• Update function documentation and add regression tests using the existing CSOM mock infrastructure and actual embedded web-part mappings.

The fallback preserves a supported embed's reference; it does not mark the embed type unsupported, recover the file, or promise working playback. A file-not-found response alone does not establish whether the URL is broken, the file was deleted, or access restrictions conceal it.

Automated verification

Executed against this implementation with .NET SDK 10.0.402, Debug configuration, net10.0:

dotnet test .\src\lib\PnP.Framework.Modernization.Test\PnP.Framework.Modernization.Test.csproj --no-restore --filter "FullyQualifiedName~BuiltInDocumentEmbedLookupTests|FullyQualifiedName~BuiltInImageLookupTests" --logger "console;verbosity=normal" --verbosity quiet

21 passed, 0 failed, 0 skipped: 11 new document-embed cases and 10 existing image-lookup/mapping cases.

Coverage	Cases	Verified behavior
Null and empty document paths	2	Non-null result with exactly all five metadata keys and empty values
Successful document retrieval	1	Correct web URL, list ID, unique ID, author account, and author name
File not found in the current web	1	Complete empty metadata; one actionable warning containing path/context; no transformation error log
File not found during another web's discovery	1	Same fallback contract and warning behavior
Explicit access denied and unexpected server errors	2	Original exception type propagates and is logged; no file-not-found warning
Actual wiki embed, Media Web Part, Excel, and Visio mappings	4	FunctionProcessor.Process completes; subsequent author encoding succeeds; metadata definitions and values exist; token substitution produces parseable JSON; original absolute/server-relative references remain; unavailable metadata is empty
Existing image lookup and mapping regressions	10	Dimension defaults, successful values, skipped/missing-file handling, and numeric JSON properties remain intact

git diff --check passed. The existing NU1902 warning for Microsoft.Build.Tasks.Git 8.0.0 remains outside this change.

Live SharePoint verification

Performed on October 19, 2026 using certificate-based application authentication in an authorized SharePoint Online test environment. The harness referenced this worktree's patched project and used the build's embedded web-part mappings. These were real transformations followed by independent reads of the persisted pages, not only mocked lookup tests.

Two affected enterprise-wiki publishing pages were transformed in the same web into uniquely named SitePages copies with overwrite disabled. Tenant identifiers, exact page/media URLs, page content, authentication configuration, and raw logs are omitted from this public PR and retained locally.

Live case	File-not-found embeds	Migration result	Independent saved-page verification
Publishing page A	2 embeds referencing one unavailable WMV file	Completed; 2 lookup warnings; no transformation error entries	Both references retained, empty IDs/author metadata, body text present, no unresolved metadata tokens
Publishing page B	3 embeds referencing two unavailable MP4 files	Completed; 3 lookup warnings; no transformation error entries	All three references retained, empty IDs/author metadata, body text present, no unresolved metadata tokens

Additional verification:

• SharePoint still returned File Not Found during conversion, confirming the fallback was exercised without repairing the source files.
• Both saved target pages existed and had non-empty CanvasContent1.
• Parsed the persisted web-part JSON and compared the complete media-reference multiset with the source web parts, including duplicates and absolute/server-relative URL consistency.
• Confirmed source file identities, version labels, and modification timestamps were unchanged.
• PublishCreatedPage=false was used, but the target library has major-only versioning and moderation disabled, so SharePoint saved the isolated copies as published major versions. No library settings were changed.

Limitations

• Verified conversion, warning emission, persisted body text, and reference preservation, not working playback or browser-rendered visual fidelity.
• Live coverage was same-web enterprise-wiki publishing transformation with Media Web Parts. Wiki document, Excel, Visio, and hosting-web-discovery fallback coverage is automated; no live cross-site migration claim is made.
• The targeted suite was run, not the full test suite or every target-framework build.