{"record":{"id":"bcc452e0c05886c0","repo":"microsoft/aspire","slug":"the-node-modules-mode-must-be-a-defined","errorCode":null,"errorMessage":"The node_modules mode must be a defined DenoNodeModulesDirMode value.","messagePattern":"The node_modules mode must be a defined DenoNodeModulesDirMode value\\.","errorType":"validation","errorClass":"ArgumentOutOfRangeException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.JavaScript/DenoHostingExtensions.cs","lineNumber":230,"sourceCode":"    /// <c>--node-modules-dir=&lt;mode&gt;</c>.\n    /// </summary>\n    /// <param name=\"builder\">The Deno app resource builder.</param>\n    /// <param name=\"mode\">The node_modules mode. When <see langword=\"null\"/>, emits <c>--node-modules-dir</c> without a value.</param>\n    /// <returns>A reference to the <see cref=\"IResourceBuilder{T}\"/>.</returns>\n    /// <exception cref=\"ArgumentOutOfRangeException\">Thrown when <paramref name=\"mode\"/> is not a defined <see cref=\"DenoNodeModulesDirMode\"/> value.</exception>\n    /// <ats-returns>The resource builder.</ats-returns>\n    /// <remarks>\n    /// The generated Deno Dockerfile publisher does not support <c>manual</c> mode because it excludes local\n    /// <c>node_modules</c> from the build context. Use <c>auto</c> or provide a custom Dockerfile for that mode.\n    /// </remarks>\n    [AspireExport]\n    [Experimental(\"ASPIREDENO001\", UrlFormat = \"https://aka.ms/aspire/diagnostics/{0}\")]\n    public static IResourceBuilder<DenoAppResource> WithDenoNodeModulesDir(this IResourceBuilder<DenoAppResource> builder, DenoNodeModulesDirMode? mode = null)\n    {\n        ArgumentNullException.ThrowIfNull(builder);\n        if (mode is not null && !Enum.IsDefined(mode.Value))\n        {\n            throw new ArgumentOutOfRangeException(nameof(mode), mode, \"The node_modules mode must be a defined DenoNodeModulesDirMode value.\");\n        }\n\n        var annotation = GetOrAddDenoAnnotation(builder);\n        annotation.NodeModulesDirSet = true;\n        annotation.NodeModulesDirMode = mode;\n        return builder;\n    }\n\n    // ---- Unstable flags ---------------------------------------------------------------------\n\n    /// <summary>\n    /// Adds one or more <c>--unstable-*</c> flags. Each feature may be supplied bare (for example <c>\"kv\"</c>,\n    /// <c>\"worker-options\"</c>, <c>\"sloppy-imports\"</c>) or fully qualified (<c>\"--unstable-kv\"</c>).\n    /// </summary>\n    /// <param name=\"builder\">The Deno app resource builder.</param>\n    /// <param name=\"features\">The unstable feature names or fully-qualified <c>--unstable-*</c> flags to emit.</param>\n    /// <returns>A reference to the <see cref=\"IResourceBuilder{T}\"/>.</returns>\n    /// <ats-returns>The resource builder.</ats-returns>","sourceCodeStart":212,"sourceCodeEnd":248,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.JavaScript/DenoHostingExtensions.cs#L212-L248","documentation":"WithDenoNodeModulesDir validates the optional DenoNodeModulesDirMode before recording it on the annotation. Passing a value that is not a defined enum member (bad cast or version mismatch) would produce an unsupported 'node-modules-dir' value later, so the library throws ArgumentOutOfRangeException immediately.","triggerScenarios":"Calling WithDenoNodeModulesDir with a mode cast from an int/string that is not None/Auto/Manual, or with a value from a mismatched Aspire.Hosting.JavaScript assembly version.","commonSituations":"Reading a node-modules mode from configuration and casting directly; stale binary referencing enum members added or renumbered elsewhere; helper code generating enum values.","solutions":["Pass DenoNodeModulesDirMode.None/Auto/Manual, or call WithDenoNodeModulesDir() with no argument to use the default.","Validate with Enum.IsDefined before casting config input.","Rebuild against matching Aspire package versions.","Update the switch/serialization map in the library when adding new enum members."],"exampleFix":"// before\nvar mode = (DenoNodeModulesDirMode)int.Parse(config[\"mode\"]);\nresource.WithDenoNodeModulesDir(mode);\n// after\nif (!Enum.TryParse<DenoNodeModulesDirMode>(config[\"mode\"], out var mode) || !Enum.IsDefined(mode))\n    throw new ArgumentException($\"Unknown node_modules mode '{config[\"mode\"]}'.\");\nresource.WithDenoNodeModulesDir(mode);","handlingStrategy":"validation","validationCode":"if (mode is not null && !Enum.IsDefined(mode.Value)) throw new ArgumentException(\"mode must be a defined DenoNodeModulesDirMode\");","typeGuard":"static bool IsValidNodeModulesMode(DenoNodeModulesDirMode? m) => m is null || Enum.IsDefined(m.Value);","tryCatchPattern":"try { resource.WithDenoNodeModulesDir(mode); } catch (ArgumentOutOfRangeException ex) when (ex.ParamName == \"mode\") { /* map to config error */ }","preventionTips":["Use TryParse + IsDefined for enum parsing from config","Reference enum members by name, never by numeric value","Keep Aspire packages version-aligned"],"tags":["argument-exception","enum","deno","validation"],"backgroundTag":"invalid-enum-value","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}