discordjs/discord.js · error · Error

The --tag option can only be used with --dev

Error message

The --tag option can only be used with --dev

What it means

The release CLI parses --tag from command options. Tags are a dev-release concept (getInput('tag') returns an empty string when unset, so the code checks length). Passing --tag without --dev is invalid because a named tag has no meaning for non-dev releases, so the script throws immediately after option parsing.

Source

Thrown at packages/actions/src/releasePackages/index.ts:49

		'-e, --exclude <packages...>',
		'exclude specific packages from releasing (will still release if necessary for another package)',
		excludeInput ? excludeInput.split(',') : [],
	)
	.option('--dry', 'skips actual publishing and outputs logs instead', dryInput)
	.option('--dev', 'publishes development versions and skips tagging / github releases', devInput)
	.option('--tag <tag>', 'tag to use for dev releases (defaults to "dev")', getInput('tag'))
	.parse();

const {
	exclude,
	dry,
	dev,
	tag: inputTag,
} = program.opts<{ dev: boolean; dry: boolean; exclude: string[]; tag: string }>();

// All this because getInput('tag') will return empty string when not set :P
if (!dev && inputTag.length) {
	throw new Error('The --tag option can only be used with --dev');
}

const tag = inputTag.length ? inputTag : dev ? 'dev' : undefined;
const [packageName] = program.processedArgs as [string];
const tree = await generateReleaseTree(dry, tag, packageName, exclude);

interface ReleaseResult {
	identifier: string;
	url: string;
}

const publishedPackages: ReleaseResult[] = [];
const skippedPackages: ReleaseResult[] = [];

for (const branch of tree) {
	startGroup(`Releasing ${branch.map((entry) => `${entry.name}@${entry.version}`).join(', ')}`);

	await Promise.all(

View on GitHub (pinned to a81ed8a306)

Solutions

1. Add the --dev flag when using --tag.
2. Remove the --tag option if you intend a normal (non-dev) release.
3. Fix the CI workflow/script so tag is only passed when dev mode is enabled.

Example fix

// before
pnpm release all --tag nightly
// after
pnpm release all --dev --tag nightly

if (!dev && inputTag.length) {
  throw new Error('The --tag option can only be used with --dev');
}

const isDevTagOptions = (o: { dev: boolean; tag: string }) => !o.tag.length || o.dev;

try {
  await runRelease(args);
} catch (err) {
  if ((err as Error).message.includes('--tag option can only be used with --dev')) {
    console.error('Invalid flags: either drop --tag or add --dev.');
    process.exitCode = 1;
  } else throw err;
}

When it happens

Trigger: Invoking the release CLI with `--tag <value>` but without the `--dev` flag, i.e. `!dev && inputTag.length` is true.

Common situations: Copy-pasting a dev-release command and dropping --dev; CI templates that always inject a tag argument; scripting the release command with variables where tag is set but dev is false.

Related errors

• Package ${packageName} not releaseable
• Reduce of empty collection with no initial value
• ClientMissingIntents
• Cannot set an interval greater than 4 hours
• Expected token to be set for this request, but none was pres

AI-assisted analysis of discordjs/discord.js@a81ed8a306 (2026-08-30). Data as JSON: /api/errors/ee8e6c1cf2ed1d7b. Report an issue: GitHub.