{"record":{"id":"d106b7124c7d3ad9","repo":"RicoSuter/NSwag","slug":"the-specified-runtime-in-the-document-document-runtime","errorCode":null,"errorMessage":"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.","messagePattern":"The specified runtime in the document \\((.+?)\\) differs from the current process runtime \\((.+?)\\)\\. Change the runtime with the '/runtime:(.+?)' parameter or run the file with the correct command line binary\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/NSwag.Commands/Commands/Document/ExecuteDocumentCommand.cs","lineNumber":65,"sourceCode":"                }\n                else if (!hasNSwagJson)\n                {\n                    host.WriteMessage(\"Current directory does not contain any .nswag files.\");\n                }\n            }\n            return null;\n        }\n\n        private async Task ExecuteDocumentAsync(IConsoleHost host, string filePath)\n        {\n            host.WriteMessage(\"\\nExecuting file '\" + filePath + \"' with variables '\" + Variables + \"'...\\n\");\n\n            var document = await NSwagDocument.LoadWithTransformationsAsync(filePath, Variables);\n            if (document.Runtime != Runtime.Default)\n            {\n                if (document.Runtime != RuntimeUtilities.CurrentRuntime)\n                {\n                    throw new InvalidOperationException(\"The specified runtime in the document (\" + document.Runtime + \") differs \" +\n                                                        \"from the current process runtime (\" + RuntimeUtilities.CurrentRuntime + \"). \" +\n                                                        \"Change the runtime with the '/runtime:\" + document.Runtime + \"' parameter \" +\n                                                        \"or run the file with the correct command line binary.\");\n                }\n            }\n\n            await document.ExecuteAsync();\n            host.WriteMessage(\"Done.\\n\");\n        }\n    }\n}\n","sourceCodeStart":47,"sourceCodeEnd":77,"githubUrl":"https://github.com/RicoSuter/NSwag/blob/63daf8fcc3a25151b62eb4b326a1e8ea048a0d41/src/NSwag.Commands/Commands/Document/ExecuteDocumentCommand.cs#L47-L77","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before (file.nswag)\n\"runtime\": \"NetCore31\"\n// after\n\"runtime\": \"Net80\"\n// or run with: nswag run file.nswag /runtime:Net80","handlingStrategy":"validation","validationCode":"var doc = Newtonsoft.Json.Linq.JObject.Parse(File.ReadAllText(nswagFile));\nvar runtime = doc[\"runtime\"]?.ToString() ?? \"Default\";\nConsole.WriteLine($\"Document runtime: {runtime}; ensure the matching nswag binary or /runtime flag.\");","typeGuard":"bool RuntimeMatches(string documentRuntime, string currentRuntime) => documentRuntime == \"Default\" || documentRuntime == currentRuntime;","tryCatchPattern":"try { await documentCommand.RunAsync(); }\ncatch (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; }","preventionTips":["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."],"tags":["cli","runtime-mismatch","configuration","nswag"],"backgroundTag":"unsupported-platform","analyzedSha":"63daf8fcc3a25151b62eb4b326a1e8ea048a0d41","analyzedAt":"2026-09-14T11:38:15.205Z","contentChangedAt":"2026-09-14T11:38:15.205Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}