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.

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.
Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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; }

Prevention

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

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

Appendix: 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)