agalwood/Motrix · error · PluginEngineVersionTooOld

PLUGIN_ENGINE_VERSION_TOO_OLD

PLUGIN_ENGINE_VERSION_TOO_OLD

Error message

Plugin requires host ${required}; running ${hostVersion}

What it means

Thrown as PluginEngineVersionTooOld (a distinct error code, NOT PluginManifestInvalid) when the plugin's engines.motrix range is not satisfied by opts.hostVersion. It runs AFTER successful JSON parse but BEFORE Zod schema validation, so a plugin can be rejected for the host being too old even if structurally valid. The message names both the required range and the running host version.

Source

Thrown at src/core/plugin/manifest/parse.ts:154

  } catch (e) {
    throw new PluginManifestInvalid(
      'plugin.manifest.invalid',
      `manifest is not valid JSON: ${(e as Error).message}`
    )
  }

  // Step 1: Read engines.motrix BEFORE strict schema validation.
  const enginesMotrix =
    typeof parsed === 'object' &&
    parsed !== null &&
    'engines' in parsed &&
    typeof (parsed as { engines: unknown }).engines === 'object' &&
    (parsed as { engines: { motrix?: unknown } }).engines !== null
      ? (parsed as { engines: { motrix?: unknown } }).engines.motrix
      : undefined
  if (typeof enginesMotrix === 'string') {
    if (!semverSatisfies(opts.hostVersion, enginesMotrix)) {
      throw new PluginEngineVersionTooOld(enginesMotrix, opts.hostVersion)
    }
  }

  // Step 2: Apply strict schema validation.
  const result = ManifestSchema.safeParse(parsed)
  if (!result.success) {
    throw new PluginManifestInvalid(
      'plugin.manifest.invalid',
      'manifest failed schema validation',
      result.error.issues
    )
  }

  // Step 3: Enforce reserved-publisher invariant. Community plugins must not
  // claim a reserved publisher (motrix.*, verified.*, official.*, system.*).
  // Built-ins shipped inside the app bundle are exempt — they originate from
  // <resourcesDir>/builtin-plugins/ and the registry passes origin='builtin'.
  const origin = opts.origin ?? 'community'

View on GitHub (pinned to 1a708ee577)

Solutions

1. Update Motrix to a version that satisfies the plugin's engines.motrix range.
2. If you are the author, lower engines.motrix to match the oldest host you support, or backport the API usage.
3. Before installing, check semverSatisfies(hostVersion, manifest.engines.motrix) and surface a friendly message.

Example fix

// before — plugin requires ^3.0.0, host is 2.5.0
// manifest.json: { "engines": { "motrix": "^3.0.0" } }
// after — author widens support to 2.5+
// { "engines": { "motrix": ">=2.5.0" } }

import { semverSatisfies } from './parse'
// peek engines.motrix from the raw JSON before full parse
const peek = JSON.parse(raw)
const range = peek?.engines?.motrix
if(typeof range==='string' && !semverSatisfies(hostVersion, range)){
  throw new Error(`host ${hostVersion} does not satisfy plugin range ${range}`)
}

try { parseManifest(raw, {hostVersion}) }
catch(e){ if(e instanceof PluginEngineVersionTooOld){ /* prompt user to update Motrix or pick a compatible plugin */ } else throw e }

When it happens

Trigger: Plugin declares engines.motrix='^3.0.0' and the host is on 2.5.0; plugin requires '>=2.5.0' and host is 2.4.1; semverSatisfies returns false for the host/range pair.

Common situations: User on an older Motrix tries a plugin built for a newer API; plugin author set engines too high; host has not been updated.

Related errors

• PLUGIN_MANIFEST_INVALID
• transient-failure
• plugin.command.not_declared_in_manifest
• PluginManifestInvalid
• plugin.manifest.role.requires_builtin

AI-assisted analysis of agalwood/Motrix@1a708ee577 (2026-08-12). Data as JSON: /api/errors/a7678763e41649de. Report an issue: GitHub.