n8n-io/n8n · error · UserError

The --file flag is no longer supported. Please first import

Error message

The --file flag is no longer supported. Please first import the workflow and then execute it using the --id flag.

What it means

The `n8n execute` command throws UserError when --file is passed. The --file flag was removed; workflows must now be imported first and executed via --id. Message includes the migration instruction. The check fires only after --id is verified present.

Source

Thrown at packages/cli/src/commands/execute.ts:53

	async init() {
		await super.init();
		await this.initLicense();
		await this.initCommunityPackages();
		await this.initBinaryDataService();
		await this.initDataDeduplicationService();
		await this.initExternalHooks();
	}

	async run() {
		const { flags } = this;

		if (!flags.id) {
			this.logger.info('"--id" has to be set!');
			return;
		}

		if (flags.file) {
			throw new UserError(
				'The --file flag is no longer supported. Please first import the workflow and then execute it using the --id flag.',
				{ level: 'warning' },
			);
		}

		let workflowId: string | undefined;
		let workflowData: IWorkflowBase | null = null;

		if (flags.id) {
			// Id of workflow is given
			workflowId = flags.id;
			workflowData = await Container.get(WorkflowRepository).findOneBy({ id: workflowId });
			if (workflowData === null) {
				this.logger.info(`The workflow with the id "${workflowId}" does not exist.`);
				process.exit(1);
			}
		}

View on GitHub (pinned to 5ac6606e81)

Solutions

Import the workflow first: `n8n import:workflow --input=workflow.json`, then `n8n execute --id=<id>`.
Update any scripts/docs that still reference --file to the import+execute flow.

Example fix

# before
n8n execute --file=workflow.json

# after
n8n import:workflow --input=workflow.json
n8n execute --id=<imported-workflow-id>

Defensive patterns

Strategy: validation

Validate before calling

// Before invoking, strip legacy flags
const flags = { ...rawFlags };
if ('file' in flags) { /* redirect to import:workflow + execute --id */ }
delete flags.file;

Type guard

function isRemovedFlagError(error: unknown): boolean {
  return error instanceof Error && error.message.includes('--file flag is no longer supported');
}

Try / catch

try {
  await Execute.run(argv);
} catch (e) {
  if (isRemovedFlagError(e)) { /* run import:workflow then execute --id */ }
  else throw e;
}

Prevention

Update all scripts/docs to the import-then-execute flow.
Always pass --id when automating executions.
Track n8n release notes for CLI flag removals.

When it happens

Trigger: Invoking `n8n execute --file=workflow.json` (with or without --id). The legacy flag is hard-rejected.

Common situations: Script or docs referencing the old --file execution mode after upgrading n8n; muscle-memory CLI invocation from pre-migration workflows.

Related errors

AI-assisted analysis of n8n-io/n8n@5ac6606e81 (2026-08-12). Data as JSON: /api/errors/5e7e25c79b826660. Report an issue: GitHub.