{"record":{"id":"f906382094ad475c","repo":"halo-dev/halo","slug":"esm-provider-manifest-must-be-an-object","errorCode":null,"errorMessage":"ESM provider manifest must be an object.","messagePattern":"ESM provider manifest must be an object\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"ui/packages/ui-plugin-bundler-kit/src/provider-manifest.ts","lineNumber":15,"sourceCode":"import path from \"node:path\";\n\nexport const ESM_PROVIDER_MANIFEST = \"ui-plugin.json\";\n\nexport interface EsmProviderManifest {\n  format: \"esm\";\n  entry: string;\n  style?: string;\n}\n\nexport function validateEsmProviderManifest(\n  value: unknown\n): EsmProviderManifest {\n  if (!isRecord(value)) {\n    throw new Error(\"ESM provider manifest must be an object.\");\n  }\n  const keys = Object.keys(value).sort();\n  if (\n    !keys.includes(\"entry\") ||\n    !keys.includes(\"format\") ||\n    keys.some((key) => ![\"entry\", \"format\", \"style\"].includes(key)) ||\n    value.format !== \"esm\"\n  ) {\n    throw new Error(\n      'ESM provider manifest must contain format, entry, and optional style only with format \"esm\".'\n    );\n  }\n  if (typeof value.entry !== \"string\") {\n    throw new Error(\"ESM provider manifest entry is required.\");\n  }\n  const manifest: EsmProviderManifest = {\n    format: \"esm\",\n    entry: normalizeProviderResourcePath(value.entry),","sourceCodeStart":1,"sourceCodeEnd":33,"githubUrl":"https://github.com/halo-dev/halo/blob/d2f5165f9c8f055ffcb3fa9c3f4032821a7b68c8/ui/packages/ui-plugin-bundler-kit/src/provider-manifest.ts#L1-L33","documentation":"Thrown by PluginServiceImpl.satisfiesRequiresVersion during install()/upgrade() when the plugin's spec.requires (a SemVer range) is not satisfied by the running Halo system version (compared on the nominal MAJOR.MINOR.PATCH only). It is an UnsatisfiedAttributeValueException (ServerWebInputException, HTTP 400) with messageDetailCode problemDetail.plugin.version.unsatisfied.requires and detail arguments [requires, systemVersion].","triggerScenarios":"Installing or upgrading a plugin whose plugin.yaml spec.requires (e.g. \">=2.10.0\") evaluates false against the current Halo version.","commonSituations":"Deploying a plugin built for a newer Halo onto an older instance; bumping spec.requires during plugin development past the local dev server version; operator running an outdated Halo patch line.","solutions":["Upgrade Halo to a release whose MAJOR.MINOR.PATCH satisfies spec.requires.","Lower spec.requires in plugin.yaml to a range your Halo satisfies — only if the plugin's APIs are actually compatible.","Confirm you are reading the stable version: comparison ignores pre-release/build metadata."],"exampleFix":"// before\nspec:\n  requires: \">=2.20.0\"\n// after — compatible with the running 2.10.x line\nspec:\n  requires: \">=2.10.0\"","handlingStrategy":"validation","validationCode":"// Compare plugin.requires against the runtime system version before install.\nString sys = systemVersionSupplier.get().toStableVersion().toString();\nString requires = candidate.getSpec().getRequires();\nif (!VersionUtils.satisfiesRequires(sys, requires)) {\n    // block install: requires > system version\n}","typeGuard":null,"tryCatchPattern":"pluginService.install(path)\n    .onErrorResume(UnsatisfiedAttributeValueException.class, e ->\n        Mono.error(new BusinessException(\"Plugin requires a newer Halo: \" + Arrays.toString(e.getDetailArguments())))","preventionTips":["Document the minimum Halo version in your plugin's README and CI matrix.","Set spec.requires to the lowest Halo version you actually test against.","Upgrade Halo before installing plugins built for newer releases."],"tags":["plugin","versioning","install","system-version","validation"],"backgroundTag":null,"analyzedSha":"d2f5165f9c8f055ffcb3fa9c3f4032821a7b68c8","analyzedAt":"2026-08-14T00:18:38.915Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}