immich-app/immich · error · BadRequestException

Unknown method

Error message

Unknown method ${step.method}

What it means

resolveAndValidateSteps looks up each requested step's method in the plugin repository's available methods (resolveMethod). When no plugin method matches the given step.method name, the step cannot be resolved and a 400 Bad Request 'Unknown method <name>' is thrown.

Solutions

1. Fetch the current list of available plugin methods (validation endpoint) and use an exact, existing method id.
2. Check for typos and case mismatches in step.method.
3. Install/enable the plugin that provides the referenced method, or remove the step.
4. Refresh the client so its method list matches the server's installed plugins.

Example fix

// before
{ "steps": [{ "method": "uploadAsset" }] }
// after
// use a method id returned by the plugin methods endpoint
{ "steps": [{ "method": "asset.upload" }] }

const methods = await api.getPluginMethods();
const known = new Set(methods.map((m) => m.id));
for (const step of steps) {
  if (!known.has(step.method)) {
    throw new Error(`Unknown method ${step.method}`);
  }
}

const isKnownMethod = (m: string, known: Set<string>): m is PluginMethodId => known.has(m);

try {
  await api.createWorkflow({ trigger, steps });
} catch (e) {
  if (e instanceof BadRequestException && e.message.startsWith('Unknown method')) {
    // refresh method list and correct the step
  }
}

When it happens

Trigger: Creating/updating a workflow (via the steps endpoint) where any step references a method identifier that is not in pluginRepository.getForValidation() — typo'd method names, methods of uninstalled/disabled plugins, or deprecated method ids.

Common situations: Client cache listing stale plugin methods after a plugin was updated or removed; hand-written automation scripts using guessed method names; case-sensitivity mistakes in method identifiers; workflows copied between servers with different plugins installed.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• authToken is required
• Hostname did not match any listed in methods[].allowedHosts…
• Invalid token
• Invalid token: missing userId
• Method " " is incompatible with workflow trigger

AI-assisted analysis of immich-app/immich@e55ac299a4 (2026-09-15). Data as JSON: /api/errors/7316a05bed696fb1. Report an issue: GitHub.

Appendix: source

Thrown at server/src/services/workflow.service.ts:112

      result: entry.result,
      triggerDataId: entry.triggerDataId ?? undefined,
      lastStep: entry.step
        ? {
            index: entry.step.order,
            method: `${entry.step.pluginId}#${entry.step.methodName}`,
          }
        : undefined,
    }));
  }

  private async resolveAndValidateSteps<T extends { method: string }>(steps: T[], trigger: WorkflowTrigger) {
    const methods = await this.pluginRepository.getForValidation();
    const results: Array<T & { pluginMethod: PluginMethodSearchResponse }> = [];

    for (const step of steps) {
      const pluginMethod = resolveMethod(methods, step.method);
      if (!pluginMethod) {
        throw new BadRequestException(`Unknown method ${step.method}`);
      }

      if (!isMethodCompatible(pluginMethod, trigger)) {
        throw new BadRequestException(`Method "${step.method}" is incompatible with workflow trigger: "${trigger}"`);
      }

      results.push({ ...step, pluginMethod });
    }

    // TODO make sure all steps can use a common WorkflowType

    return results;
  }

  private findOrFail(id: string) {
    return findOrFail(() => this.workflowRepository.get(id), 'Workflow');
  }
}

View on GitHub (pinned to e55ac299a4)