Fix crash when toc references a missing file

src/Elastic.Documentation.Navigation/Isolated/Node/DocumentationSetNavigation.cs

@@ -196,14 +196,18 @@ private static IFileInfo ResolveFileInfo(IDocumentationSetContext context, strin
 	private TModel? CreateDocumentationFile(
 		IFileInfo fileInfo,
 		IFileSystem fileSystem,
-		IDocumentationSetContext context,
-		string fullPath
+		IDocumentationSetContext context
 	)
 	{
 		var relativePath = Path.GetRelativePath(context.DocumentationSourceDirectory.FullName, fileInfo.FullName);
 		var documentationFile = _factory.TryCreateDocumentationFile(fileInfo, fileSystem);
 		if (documentationFile == null)
-			context.EmitError(context.ConfigurationPath, $"File navigation '{relativePath}' could not be created. {fullPath}");
+		{
+			var reason = fileInfo.Exists
+				? "the file exists but is not a valid Markdown document"
+				: "the file does not exist on disk";
+			context.EmitError(context.ConfigurationPath, $"Table of contents references '{relativePath}' but {reason}.");
+		}
 
 		return documentationFile;
 	}
@@ -248,7 +252,7 @@ INavigationHomeAccessor homeAccessor
 			DetectionRuleRef ruleRef => ruleRef.FileInfo,
 			_ => ResolveFileInfo(context, fullPath)
 		};
-		var documentationFile = CreateDocumentationFile(fileInfo, context.ReadFileSystem, context, fullPath);
+		var documentationFile = CreateDocumentationFile(fileInfo, context.ReadFileSystem, context);
 		if (documentationFile == null)
 			return null;
 

src/Elastic.Documentation.Navigation/NavigationItemExtensions.cs

@@ -120,9 +120,14 @@ private static void BuildNavigationLookupsRecursive(
 				_ = navigationByOrder.TryAdd(leaf.NavigationIndex, leaf);
 				break;
 			case INodeNavigationItem<IDocumentationFile, INavigationItem> documentationFileNode:
-				_ = navigationDocumentationFileLookup.TryAdd(documentationFileNode.Index.Model, documentationFileNode);
 				_ = navigationByOrder.TryAdd(documentationFileNode.NavigationIndex, documentationFileNode);
-				_ = navigationByOrder.TryAdd(documentationFileNode.Index.NavigationIndex, documentationFileNode.Index);
+				// Index is a null sentinel when this node's table of contents produced no items; the
+				// validation error is emitted upstream, so skip registering a missing index here.
+				if (documentationFileNode.Index is { } documentationFileIndex)
+				{
+					_ = navigationDocumentationFileLookup.TryAdd(documentationFileIndex.Model, documentationFileNode);
+					_ = navigationByOrder.TryAdd(documentationFileIndex.NavigationIndex, documentationFileIndex);
+				}
 				foreach (var child in documentationFileNode.NavigationItems)
 					BuildNavigationLookupsRecursive(child, navigationDocumentationFileLookup, navigationByOrder);
 				break;

src/Elastic.Markdown/IO/DocumentationSet.cs

@@ -129,8 +129,13 @@ private void VisitNavigation(INavigationItem item)
 					extension.VisitNavigation(item, markdownLeaf.Model);
 				break;
 			case INodeNavigationItem<IDocumentationFile, INavigationItem> node:
-				foreach (var extension in EnabledExtensions)
-					extension.VisitNavigation(node, node.Index.Model);
+				// Index is a null sentinel when this node's table of contents produced no items
+				// (a validation error is emitted upstream); skip visiting a missing index.
+				if (node.Index is { } nodeIndex)
+				{
+					foreach (var extension in EnabledExtensions)
+						extension.VisitNavigation(node, nodeIndex.Model);
+				}
 				foreach (var child in node.NavigationItems)
 					VisitNavigation(child);
 				break;

tests/Navigation.Tests/Isolation/ValidationTests.cs

@@ -3,6 +3,7 @@
 // See the LICENSE file in the project root for more information
 
 using System.IO.Abstractions.TestingHelpers;
+using System.Runtime.CompilerServices;
 using AwesomeAssertions;
 using Elastic.Documentation.Configuration.Toc;
 using Elastic.Documentation.Diagnostics;
@@ -259,6 +260,38 @@ public async Task ValidationDoesNotEmitHintForSimpleVirtualFiles()
 		context.Diagnostics.Should().BeEmpty();
 	}
 
+	[Fact]
+	public async Task BuildNavigationLookupsDoesNotThrowWhenTocReferencesMissingFile()
+	{
+		// language=yaml
+		var yaml = """
+		           project: 'test-project'
+		           toc:
+		             - file: missing.md
+		           """;
+
+		var fileSystem = new MockFileSystem();
+		fileSystem.AddDirectory("/docs");
+		// Note: /docs/missing.md is intentionally not created on disk
+		var context = CreateContext(fileSystem);
+		var docSet = DocumentationSetFile.LoadAndResolve(context.Collector, yaml, fileSystem.NewDirInfo("docs"));
+		_ = context.Collector.StartAsync(TestContext.Current.CancellationToken);
+
+		var navigation = new DocumentationSetNavigation<IDocumentationFile>(docSet, context, MissingFileDocumentationFileFactory.Instance);
+
+		var lookup = new ConditionalWeakTable<IDocumentationFile, INavigationItem>();
+		var buildLookups = () => navigation.BuildNavigationLookups(lookup);
+		buildLookups.Should().NotThrow("a missing toc file must surface a validation error, not crash the build");
+
+		await context.Collector.StopAsync(TestContext.Current.CancellationToken);
+
+		context.Collector.Errors.Should().BeGreaterThan(0);
+		var diagnostics = context.Diagnostics;
+		diagnostics.Should().Contain(d =>
+			d.Message.Contains("missing.md") &&
+			d.Message.Contains("does not exist"));
+	}
+
 	[Fact]
 	public async Task ValidationDoesNotEmitHintForFilesWithoutChildren()
 	{

tests/Navigation.Tests/TestDocumentationSetContext.cs

@@ -171,6 +171,26 @@ public TestDocumentationFile TryCreateDocumentationFile(IFileInfo path, IFileSys
 	}
 }
 
+// Factory that mirrors production behaviour: returns null when the referenced file is not present on disk.
+// Used to reproduce the missing-toc-file scenario where navigation produces a null Index sentinel.
+public class MissingFileDocumentationFileFactory : IDocumentationFileFactory<IDocumentationFile>
+{
+	public static MissingFileDocumentationFileFactory Instance { get; } = new();
+
+	/// <inheritdoc />
+	public IDocumentationFile? TryCreateDocumentationFile(IFileInfo path, IFileSystem readFileSystem)
+	{
+		if (!path.Exists)
+			return null;
+
+		var fileName = path.Name;
+		var title = fileName.EndsWith(".md", StringComparison.OrdinalIgnoreCase)
+			? fileName[..^3]
+			: fileName;
+		return new TestDocumentationFile(title);
+	}
+}
+
 // Factory that creates base IDocumentationFile instances for tests that don't need concrete types
 public class GenericDocumentationFileFactory : IDocumentationFileFactory<IDocumentationFile>
 {