microsoft/semantic-kernel · error · InvalidOperationException

Error loading the manifest

Error message

Error loading the manifest

What it means

Thrown by CreateChatCompletionAgentFromDeclarativeAgentManifestAsync when the loader reports results.IsValid == true but results.Document is null. This is a defensive guard for an inconsistent loader state: the document parsed without reported problems yet no document object was produced. The message carries no interpolated detail because no specific problem was recorded.

Source

Thrown at dotnet/src/Functions/Functions.OpenApi.Extensions/Extensions/DeclarativeAgentExtensions.cs:59

        Verify.NotNullOrWhiteSpace(filePath);

        var loggerFactory = kernel.LoggerFactory;
        var logger = loggerFactory.CreateLogger(typeof(DeclarativeAgentExtensions)) ?? NullLogger.Instance;
        using var declarativeAgentFileJsonContents = DocumentLoader.LoadDocumentFromFilePathAsStream(filePath,
            logger);

        var results = await DCManifestDocument.LoadAsync(declarativeAgentFileJsonContents, new ReaderOptions
        {
            ValidationRules = [] // Disable validation rules
        }).ConfigureAwait(false);

        if (!results.IsValid)
        {
            var messages = results.Problems.Select(static p => p.Message).Aggregate(static (a, b) => $"{a}, {b}");
            throw new InvalidOperationException($"Error loading the manifest: {messages}");
        }

        var document = results.Document ?? throw new InvalidOperationException("Error loading the manifest");
        var manifestDirectory = Path.GetDirectoryName(filePath);
        document.Instructions = await GetEffectiveInstructionsAsync(manifestDirectory, document.Instructions, logger, cancellationToken).ConfigureAwait(false);

        var agent = new T
        {
            Name = document.Name,
            Instructions = document.Instructions,
            Kernel = kernel,
            Arguments = new KernelArguments(promptExecutionSettings ?? new PromptExecutionSettings()
            {
                FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(),
            }),
            Description = document.Description,
            LoggerFactory = loggerFactory,
            Id = string.IsNullOrEmpty(document.Id) ? Guid.NewGuid().ToString() : document.Id!,
        };

        if (document.Capabilities is { Count: > 0 })

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Inspect the raw manifest content - if it is empty or trivially structured, add the required top-level fields (name, instructions).
2. Update the Microsoft.Plugins.Manifest package to match the manifest schema version you are authoring against.
3. If reproducible with a well-formed manifest, file an issue with the manifest contents; the loader should not return IsValid=true with a null Document.
4. As a workaround, validate the document is non-empty before calling the SK API.

var info = new FileInfo(filePath);
if (info.Length == 0) throw new InvalidOperationException("Declarative agent manifest is empty.");

try { await kernel.CreateChatCompletionAgentFromDeclarativeAgentManifestAsync<T>(path, ct); }
catch (InvalidOperationException ex) when (ex.Message == "Error loading the manifest")
{ logger.LogError(ex, "Loader returned a null document despite IsValid=true."); throw; }

When it happens

Trigger: An edge case in DCManifestDocument.LoadAsync where the ReadResult is marked valid but the Document property is null - typically a malformed-but-tolerated manifest that the loader silently accepted as valid while producing no bound object. Rare in practice; usually indicates a loader bug or an unusual empty document.

Common situations: An essentially empty manifest file (e.g. just '{}' or '---'); a manifest with a recognized root but zero recognizable content; a version mismatch between Microsoft.Plugins.Manifest and the manifest authoring format.

Related errors

• Error loading the manifest: {messages}
• Invalid manifest file path.
• [{s_namespace}] {name} resource not found
• CopilotAgent file not found: {filePath}
• Error loading the manifest: {messages}

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/f61be9af0b5cf295. Report an issue: GitHub.