{"record":{"id":"e62f4a331edeeabf","repo":"dotnet/runtime","slug":"unrecognized-asset-behavior-asset-behavior-for","errorCode":null,"errorMessage":"Unrecognized asset behavior:${asset.behavior}, for asset ${asset.name}","messagePattern":"Unrecognized asset behavior:(.+?), for asset (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/mono/browser/runtime/assets.ts","lineNumber":61,"sourceCode":"            const lastSlash = virtualName.lastIndexOf(\"/\");\n            let parentDirectory = (lastSlash > 0)\n                ? virtualName.substring(0, lastSlash)\n                : browserVirtualAppBase;\n            let fileName = (lastSlash > 0)\n                ? virtualName.substring(lastSlash + 1)\n                : virtualName;\n            if (fileName.startsWith(\"/\"))\n                fileName = fileName.substring(1);\n            if (!parentDirectory.startsWith(\"/\"))\n                parentDirectory = browserVirtualAppBase + parentDirectory;\n\n            mono_log_debug(() => `Creating file '${fileName}' in directory '${parentDirectory}'`);\n            Module.FS_createPath(\"/\", parentDirectory, true, true);\n            Module.FS_createDataFile(parentDirectory, fileName, bytes, true /* canRead */, true /* canWrite */, true /* canOwn */);\n            break;\n        }\n        default:\n            throw new Error(`Unrecognized asset behavior:${asset.behavior}, for asset ${asset.name}`);\n    }\n\n    if (asset.behavior === \"assembly\") {\n        // this is reading flag inside the DLL about the existence of PDB\n        // it doesn't relate to whether the .pdb file is downloaded at all\n        const hasPdb = cwraps.mono_wasm_add_assembly(virtualName, offset!, bytes.length);\n\n        if (!hasPdb) {\n            const index = loaderHelpers._loaded_files.findIndex(element => element.file == virtualName);\n            loaderHelpers._loaded_files.splice(index, 1);\n        }\n    } else if (asset.behavior === \"pdb\") {\n        cwraps.mono_wasm_add_assembly(virtualName, offset!, bytes.length);\n    } else if (asset.behavior === \"icu\") {\n        wasm_load_icu_data(offset!);\n    } else if (asset.behavior === \"resource\") {\n        cwraps.mono_wasm_add_satellite_assembly(virtualName, asset.culture || \"\", offset!, bytes.length);\n    }","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/dotnet/runtime/blob/290d5ab72cc1102813fbc0406fb186ceadabc340/src/mono/browser/runtime/assets.ts#L43-L79","documentation":"Thrown by instantiate_asset() in assets.ts when an asset's `behavior` field does not match any of the cases handled by the switch: dotnetwasm, js-module-diagnostics, symbols, resource, assembly, pdb, heap, icu, vfs. The .NET WASM runtime boot config (dotnet.boot.js / mono-config.json) describes each downloadable asset with a behavior that tells the loader how to materialize it; an unrecognized value means the loader cannot decide what to do with the bytes and aborts. JS-module behaviors (js-module-dotnet/runtime/native/library-initializer, manifest) are intentionally handled elsewhere, so reaching this default case is a real mismatch, not a normal path.","triggerScenarios":"Calling instantiate_asset() with an AssetEntry whose `behavior` is a typo, an unknown string, undefined/null, or a behavior that belongs to a newer/older runtime than the loaded JS. Hand-editing mono-config.json or a custom loadBootResource callback that fabricates asset entries with wrong behavior values. Mixing a boot config generated by one WasmAppBuilder version with runtime JS from another.","commonSituations":"Upgrading the .NET SDK without rebuilding the WASM app (boot config references a behavior the old/new runtime JS disagrees on). Manually editing the generated dotnet.boot.js or its embedded mono-config. A custom CDN proxy that rewrites asset metadata. Downgrading runtime JS while keeping a newer boot manifest.","solutions":["Inspect the full error message: the literal behavior value and asset name tell you exactly which entry is wrong.","Regenerate the boot config: run `dotnet publish` (or your WASM build target) with the SAME SDK/runtime version as the runtime JS being served, so WasmAppBuilder emits only behaviors this runtime understands.","Clear the browser cache and any CDN/ServiceWorker cache of dotnet.boot.js and the framework files so a stale manifest is not served against fresh runtime JS.","If using a custom loadBootResource callback, verify you return Response/Promise for the right `behavior` and do not mutate `behavior` to an unsupported value; map unknown behaviors to null to use default loading.","If you hand-edited mono-config.json, restore it from the build output and apply only documented overrides."],"exampleFix":"// before: boot config / custom asset with a typo\n{ \"name\": \"MyLib.dll\", \"behavior\": \"asembly\" }  // typo -> default case throws\n\n// after: regenerate or correct to a known behavior\n{ \"name\": \"MyLib.dll\", \"behavior\": \"assembly\" }","handlingStrategy":"validation","validationCode":"import type { AssetBehaviors } from \"./types\";\nconst KNOWN: ReadonlySet<string> = new Set([\n  \"dotnetwasm\", \"js-module-diagnostics\", \"symbols\", \"resource\",\n  \"assembly\", \"pdb\", \"heap\", \"icu\", \"vfs\",\n  \"js-module-dotnet\", \"js-module-runtime\", \"js-module-native\",\n  \"js-module-library-initializer\", \"manifest\",\n]);\nfunction assertAssetBehavior(asset: { behavior: string; name: string }) {\n  if (!KNOWN.has(asset.behavior)) {\n    throw new Error(`Unsupported asset behavior '${asset.behavior}' for '${asset.name}'; regenerate boot config with matching SDK.`);\n  }\n}","typeGuard":"function isKnownAssetBehavior(b: unknown): b is AssetBehaviors {\n  return typeof b === \"string\" && KNOWN.has(b);\n}","tryCatchPattern":"try { instantiate_asset(asset, url, bytes); }\ncatch (e) { /* startup blocker: log asset.behavior + name, halt boot with a clear config-mismatch message */ throw e; }","preventionTips":["Never hand-edit mono-config.json / dotnet.boot.js; regenerate from a build.","Keep the SDK that generates the boot config and the runtime JS in lockstep.","If you override loadBootResource, do not alter the `behavior` field."],"tags":["configuration","asset-loading","boot-config","startup"],"analyzedSha":"290d5ab72cc1102813fbc0406fb186ceadabc340","analyzedAt":"2026-08-06T19:57:01.276Z","schemaVersion":2},"datasetVersion":"2026-08-06T23:17:07.152Z"}