RicoSuter/NSwag · error · InvalidOperationException

The specified runtime in the document

Error message

The specified runtime in the document ({document.Runtime}) differs from the current process runtime ({RuntimeUtilities.CurrentRuntime}). Change the runtime with the '/runtime:{document.Runtime}' parameter or run the file with the correct command line binary.

What it means

NSwag documents (NSwagDocument) can pin a target Runtime (WebApi, NetCore21, NetCore31, etc.). ExecuteDocumentCommand refuses to execute the document when the document's stored runtime differs from the runtime the current process binary was built for, throwing InvalidOperationException with instructions to change /runtime or use the right binary.

Solutions

Run the nswag binary matching the document's runtime, e.g. pass /runtime:Net80 or use the nswag.exe flavor built for that runtime.
Edit the .nswag JSON and set "runtime" to the current process runtime (e.g. 'Net80').
Regenerate/upgrade the document with the NSwagStudio version matching your installed binaries.

Example fix

// before (file.nswag)
"runtime": "NetCore31"
// after
"runtime": "Net80"
// or run with: nswag run file.nswag /runtime:Net80

Defensive patterns

Strategy: validation

Validate before calling

var doc = Newtonsoft.Json.Linq.JObject.Parse(File.ReadAllText(nswagFile));
var runtime = doc["runtime"]?.ToString() ?? "Default";
Console.WriteLine($"Document runtime: {runtime}; ensure the matching nswag binary or /runtime flag.");

Type guard

bool RuntimeMatches(string documentRuntime, string currentRuntime) => documentRuntime == "Default" || documentRuntime == currentRuntime;

Try / catch

try { await documentCommand.RunAsync(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("differs from the current process runtime")) { logger.LogError(ex, "Use the nswag binary matching the document runtime or pass /runtime"); throw; }

Prevention

Pin the nswag binary version/flavor per project (e.g. via NSwag.MSBuild or a local tool manifest) so document runtime and binary always match.
When sharing .nswag files across machines/CI, set "runtime" to the runtime the pipeline binary supports.
After upgrading .NET/NSwag, update the document's runtime field and test the pipeline once.

When it happens

Trigger: Running 'nswag run file.nswag' with a binary whose runtime differs from the document's Runtime setting (e.g. document says runtime: NetCore31 but you run the .NET 8/Net80 nswag binary); loading a shared nswag file across machines with different installed nswag binaries.

Common situations: Team shares one .nswag file but members have different nswag flavors installed (full vs. aspnetcore/dotnet binaries); CI image updated to a newer .NET while the document still pins an old runtime; upgrading NSwag and forgetting to update the runtime field.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

AI-assisted analysis of RicoSuter/NSwag@63daf8fcc3 (2026-09-14). Data as JSON: /api/errors/d106b7124c7d3ad9. Report an issue: GitHub.

Appendix: source

Thrown at src/NSwag.Commands/Commands/Document/ExecuteDocumentCommand.cs:65

                }
                else if (!hasNSwagJson)
                {
                    host.WriteMessage("Current directory does not contain any .nswag files.");
                }
            }
            return null;
        }

        private async Task ExecuteDocumentAsync(IConsoleHost host, string filePath)
        {
            host.WriteMessage("\nExecuting file '" + filePath + "' with variables '" + Variables + "'...\n");

            var document = await NSwagDocument.LoadWithTransformationsAsync(filePath, Variables);
            if (document.Runtime != Runtime.Default)
            {
                if (document.Runtime != RuntimeUtilities.CurrentRuntime)
                {
                    throw new InvalidOperationException("The specified runtime in the document (" + document.Runtime + ") differs " +
                                                        "from the current process runtime (" + RuntimeUtilities.CurrentRuntime + "). " +
                                                        "Change the runtime with the '/runtime:" + document.Runtime + "' parameter " +
                                                        "or run the file with the correct command line binary.");
                }
            }

            await document.ExecuteAsync();
            host.WriteMessage("Done.\n");
        }
    }
}

View on GitHub (pinned to 63daf8fcc3)