agalwood/Motrix · error · AppError

IpcInvalidPayload

IpcInvalidPayload

Error message

Invalid task create request: ${parsed.error.message}

What it means

Thrown by create-task-handler.ts:163 when `taskCreateRequestSchema.safeParse(rawRequest)` fails. The incoming IPC payload does not conform to the task-create schema; the parser's structured error is appended to the message. This is the trust-boundary validation for renderer/submitted create requests.

Source

Thrown at src/core/task/create-task-handler.ts:163

 *      subsequent polling updates merge onto an already-present record
 *      (preserving diskPath / finalPath / finalName / transitionPhase /
 *      torrentMetaPath).
 *
 * The legacy IPC contract returned only `{ gid }`; the result now also
 * carries the freshly-minted `taskId` (== DownloadTask.id) so callers
 * that need the stable public identifier (notably the MDXP bridge, where
 * gid can rotate across instance swaps) don't have to reach into
 * TaskManager to look it up. Renderer-facing IPC paths still narrow to
 * `{ gid }` structurally — the extra field is harmless excess.
 */
export async function handleCreateTask(
  rawRequest: unknown,
  deps: CreateTaskDeps,
  opts: CreateTaskOptions = {}
): Promise<{ gid: string; taskId: string }> {
  const parsed = taskCreateRequestSchema.safeParse(rawRequest)
  if (!parsed.success) {
    throw new AppError(
      ErrorCode.IpcInvalidPayload,
      `Invalid task create request: ${parsed.error.message}`
    )
  }

  const req = parsed.data
  const appSettings = deps.settingsManager.getApp()
  const engineSettings = deps.settingsManager.getEngine()

  const requestedSaveDir = req.saveDir || appSettings.defaultSaveDir
  const effectiveSaveDir = deps.prepareSaveDir
    ? await deps.prepareSaveDir(requestedSaveDir)
    : requestedSaveDir

  log.info(
    {
      type: req.type,
      payloadKind: req.type === 'bt' ? req.payload.kind : 'http',

View on GitHub (pinned to 1a708ee577)

Solutions

1. Read `parsed.error.message` to find the offending field and align the caller's payload with `taskCreateRequestSchema`.
2. Keep renderer and main schema versions in lockstep — re-export the schema as the single source of truth.
3. Validate on the renderer side before the IPC call to give the user immediate feedback.
4. If extending the payload, add new fields as optional and migrate the renderer first.

Example fix

// before
const parsed = taskCreateRequestSchema.safeParse(rawRequest)
if (!parsed.success) {
  throw new AppError(ErrorCode.IpcInvalidPayload, `Invalid task create request: ${parsed.error.message}`)
}

// after — surface zod issues to the caller for actionable feedback
const parsed = taskCreateRequestSchema.safeParse(rawRequest)
if (!parsed.success) {
  const issues = parsed.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; ')
  throw new AppError(ErrorCode.IpcInvalidPayload, `Invalid task create request: ${issues}`)
}

import { taskCreateRequestSchema } from '@shared/schemas/task-create'
const check = taskCreateRequestSchema.safeParse(candidate)
if (!check.success) {
  const issues = check.error.issues.map(i => `${i.path.join('.')}: ${i.message}`)
  // show issues to the user before sending the IPC
}

function isInvalidPayload(e) { return e instanceof AppError && e.code === ErrorCode.IpcInvalidPayload }

const parsed = taskCreateRequestSchema.safeParse(rawRequest)
if (!parsed.success) {
  throw new AppError(ErrorCode.IpcInvalidPayload, `Invalid task create request: ${parsed.error.issues.map(i => i.path.join('.') + ': ' + i.message).join('; ')}`)
}

When it happens

Trigger: Missing required fields (e.g. no `uris`); wrong field types (uris not array, saveDir not string); malformed URI entries; extra/renamed fields after a schema change without renderer update; a third-party caller sending an outdated payload shape.

Common situations: Renderer/schema version skew after an update; a browser-protocol or external caller sending hand-rolled JSON; copy-paste error in the request construction; i18n/escape bug corrupting the payload.

Related errors

• IpcInvalidPayload
• taskId must be a string
• invalid-url-scheme
• invalid Chrome extension ID: ${id}
• invalid Firefox extension ID: ${id}

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