immich-app/immich · error · BadRequestException

Method " " is incompatible with workflow trigger

Error message

Method "${step.method}" is incompatible with workflow trigger: "${trigger}"

What it means

resolveAndValidateSteps checks each resolved plugin method against the workflow's trigger via isMethodCompatible. When the method exists but does not support the workflow's trigger type (e.g. an asset-triggered workflow using a manual-only method), a 400 Bad Request naming both the method and trigger is thrown.

Solutions

1. Choose a method that supports the workflow's trigger — check the plugin method's compatible-triggers metadata.
2. Change the workflow's trigger type to one the existing steps support.
3. Remove or replace the incompatible step.
4. After a plugin update, re-validate existing workflows; rebuild steps whose trigger compatibility changed.

Example fix

// before
// trigger: manual, but method only supports asset events
{ "trigger": "manual", "steps": [{ "method": "asset.tagPeople" }] }
// after
{ "trigger": "asset-upload", "steps": [{ "method": "asset.tagPeople" }] }

const methods = await api.getPluginMethods();
const compatible = (m: string, trigger: Trigger) => {
  const pm = methods.find((x) => x.id === m);
  return pm?.supportedTriggers.includes(trigger);
};
if (!steps.every((s) => compatible(s.method, trigger))) {
  throw new Error('step method incompatible with workflow trigger');
}

try {
  await api.createWorkflow({ trigger, steps });
} catch (e) {
  if (e instanceof BadRequestException && e.message.includes('is incompatible with workflow trigger')) {
    // swap the step or change the workflow trigger
  }
}

When it happens

Trigger: Creating/updating a workflow where a step's method is valid but its supported trigger set does not include the workflow's trigger (e.g. method supports 'manual' but the workflow trigger is 'asset-upload').

Common situations: Reusing a step template across workflows with different triggers; plugin updates changing which triggers a method supports; building workflows in the API without consulting method-trigger compatibility metadata; client UI bug allowing incompatible steps to be submitted.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• Unknown method
• Asset dimensions are not available for editing
• assetIds, albumId, or userId is required
• At least two people are required for merging
• authToken is required

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

Appendix: source

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

            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)