microsoft/semantic-kernel · error · InvalidOperationException

Error loading the manifest: {messages}

Error message

Error loading the manifest: {messages}

What it means

Thrown by CreatePluginFromCopilotAgentPluginAsync when PluginManifestDocument.LoadAsync reports the Copilot Agent Plugin manifest (api-plugin-v2_0.json shape) as invalid. The message aggregates every Problem.Message returned by the loader into a comma-separated list, so it lists all schema/parsing defects found in one pass.

Source

Thrown at dotnet/src/Functions/Functions.OpenApi.Extensions/Extensions/CopilotAgentPluginKernelExtensions.cs:89

        if (!File.Exists(filePath))
        {
            throw new FileNotFoundException($"CopilotAgent file not found: {filePath}");
        }

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

        var results = await PluginManifestDocument.LoadAsync(CopilotAgentFileJsonContents, 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;
        var openAPIRuntimes = document?.Runtimes?.Where(runtime => runtime.Type == RuntimeType.OpenApi).ToList();
        if (openAPIRuntimes is null || openAPIRuntimes.Count == 0)
        {
            throw new InvalidOperationException("No OpenAPI runtimes found in the manifest.");
        }

        var functions = new List<KernelFunction>();
        var documentWalker = new OpenApiWalker(new OperationIdNormalizationOpenApiVisitor());
        foreach (var runtime in openAPIRuntimes)
        {
            var manifestFunctions = document?.Functions?.Where(f => runtime.RunForFunctions.Contains(f.Name)).ToList();
            if (manifestFunctions is null || manifestFunctions.Count == 0)
            {
                logger.LogWarning("No functions found in the runtime object.");
                continue;

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Read the aggregated messages string in the exception - it names the specific fields that failed (e.g. required 'runtimes', 'name').
2. Validate the JSON syntactically first (run it through a JSON linter) and against the Copilot Agent Plugin manifest schema.
3. Confirm the top-level structure: schema, name, description, runtimes (with type OpenApi), and functions.
4. Make sure you are pointing at the plugin manifest (api-plugin-v2_0.json), not the OpenAPI spec it references.

Example fix

// before - wrong file type
await kernel.ImportPluginFromCopilotAgentPluginAsync("P", "openapi.json");

// after - point at the plugin manifest whose runtimes reference the OpenAPI spec
await kernel.ImportPluginFromCopilotAgentPluginAsync("P", "api-plugin-v2_0.json");

using var stream = File.OpenRead(filePath);
var preview = await new StreamReader(stream).ReadToEndAsync(); stream.Position = 0;
try { JsonNode.Parse(preview); } catch (JsonException ex) { throw new InvalidOperationException($"Manifest JSON is invalid: {ex.Message}"); }

try { await kernel.ImportPluginFromCopilotAgentPluginAsync(name, path, ct); }
catch (InvalidOperationException ex) when (ex.Message.StartsWith("Error loading the manifest"))
{ logger.LogError(ex, "Manifest failed validation: {Messages}", ex.Message); throw; }

When it happens

Trigger: Loading a Copilot Agent Plugin manifest JSON that is structurally invalid against the PluginManifest schema - missing required fields (name, runtimes), malformed JSON syntax, or a top-level array where an object is expected. ValidationRules are disabled in the reader, so failures come from the manifest model binding itself, not from custom rules.

Common situations: Hand-editing the manifest and breaking the JSON; using a manifest written for a newer/older schema version; copy-pasting an example that omitted required properties; trailing commas or single quotes (JSON, not JSONC); the file is actually an OpenAPI doc rather than a plugin manifest.

Related errors

• GeminiPart is invalid. One and only one property among Text,
• CopilotAgent file not found: {filePath}
• No OpenAPI runtimes found in the manifest.
• Error loading the manifest: {messages}
• Invalid choice

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