{"record":{"id":"85e5b945fcda39fc","repo":"LykosAI/StabilityMatrix","slug":"documentation-folder-is-empty-or-not-available-yet","errorCode":null,"errorMessage":"Documentation folder is empty or not available yet.","messagePattern":"Documentation folder is empty or not available yet\\.","errorType":"exception","errorClass":"DocumentationNotAvailableException","httpStatus":null,"severity":"warning","filePath":"StabilityMatrix.Core/Services/DocumentationService.cs","lineNumber":184,"sourceCode":"        catch (NotFoundException e)\n        {\n            throw new DocumentationNotAvailableException(\"Documentation repository or branch not found.\", e);\n        }\n\n        cancellationToken.ThrowIfCancellationRequested();\n\n        var prefix = DocumentationConstants.DocsRoot + \"/\";\n\n        var paths = tree\n            .Tree.Where(item =>\n                item.Type == TreeType.Blob && item.Path.StartsWith(prefix, StringComparison.Ordinal)\n            )\n            .Select(item => item.Path[prefix.Length..])\n            .Where(IsDocPage)\n            .ToList();\n\n        if (paths.Count == 0)\n            throw new DocumentationNotAvailableException(\n                \"Documentation folder is empty or not available yet.\"\n            );\n\n        return paths;\n    }\n\n    /// <summary>\n    /// Whether a docs-relative path should be shown as a navigable page.\n    /// Excludes images, .gitkeep placeholders, and non-markdown files.\n    /// </summary>\n    private static bool IsDocPage(string docsRelativePath)\n    {\n        if (docsRelativePath.StartsWith(\"images/\", StringComparison.OrdinalIgnoreCase))\n            return false;\n\n        var lastSlash = docsRelativePath.LastIndexOf('/');\n        var fileName = lastSlash < 0 ? docsRelativePath : docsRelativePath[(lastSlash + 1)..];\n        if (fileName.Equals(\".gitkeep\", StringComparison.OrdinalIgnoreCase))","sourceCodeStart":166,"sourceCodeEnd":202,"githubUrl":"https://github.com/LykosAI/StabilityMatrix/blob/af93d6ef57c01cd890d7e0ad0a9ea8c9fcda3002/StabilityMatrix.Core/Services/DocumentationService.cs#L166-L202","documentation":"After successfully listing the docs repo paths, FetchDocsPathsAsync filters them with IsDocPage. If no paths survive the filter, the documentation folder is considered empty or not yet available and DocumentationNotAvailableException is thrown. It means the repo/branch exists but contains no recognizable documentation pages under DocsRoot.","triggerScenarios":"Calling GetSectionsAsync when the configured DocumentationConstants.DocsRoot folder is missing from the repo, was renamed, contains no files passing IsDocPage (e.g. no .md pages at the expected prefix), or the branch was pushed empty/incomplete.","commonSituations":"Docs repo restructured so markdown files moved out of DocsRoot; a new/empty branch checked out; file-extension conventions changed so IsDocPage filters everything out; partial clone or CDN serving stale tree data.","solutions":["Verify the DocsRoot folder exists in the target repo/branch and contains files matching IsDocPage's expectations (extension/naming)","Check the repo/branch actually has content (e.g. view it remotely) and switch to a branch that does","Catch DocumentationNotAvailableException and render an empty/fallback docs state with a retry","Update DocumentationConstants.DocsRoot to the restructured path if the docs layout changed"],"exampleFix":"// before\nvar sections = await documentationService.GetSectionsAsync();\n// after\ntry { var sections = await documentationService.GetSectionsAsync(); }\ncatch (DocumentationNotAvailableException ex)\n{\n    logger.LogWarning(ex, \"Docs empty/unavailable\");\n    // fallback: cached docs or empty state\n}","handlingStrategy":"fallback","validationCode":"// verify docs folder has doc pages before calling the service\nvar tree = await gitApi.ListDocsPaths(Owner, RepoName, Branch);\nvar docPages = tree.Where(p => p.StartsWith(DocumentationConstants.DocsRoot + \"/\") && p.EndsWith(\".md\")).ToList();\nif (docPages.Count == 0)\n    throw new DocumentationNotAvailableException(\"No doc pages under DocsRoot\");","typeGuard":null,"tryCatchPattern":"List<string> paths;\ntry\n{\n    paths = await docs.GetSectionsAsync(); // may throw DocumentationNotAvailableException\n}\ncatch (DocumentationNotAvailableException)\n{\n    paths = LoadCachedDocsPaths() ?? new List<string>();\n}","preventionTips":["Keep DocsRoot populated with files matching IsDocPage conventions","Avoid pushing empty/incomplete docs branches; validate CI before publishing","Rename DocsRoot in constants whenever the repo layout changes","Cache last-known-good docs paths and fall back to them"],"tags":["documentation","empty-content","configuration"],"backgroundTag":"empty-result-set","analyzedSha":"af93d6ef57c01cd890d7e0ad0a9ea8c9fcda3002","analyzedAt":"2026-09-12T19:02:43.389Z","contentChangedAt":"2026-09-12T19:02:43.389Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}