discordjs/discord.js · error · DiscordjsError

ClientInvalidOption

ClientInvalidOption

Error message

ClientInvalidOption: File, specified.

What it means

ShardingManager requires a path to the shard script file as its first constructor argument. If the value is falsy (empty string, undefined, null), the constructor throws ClientInvalidOption('File', 'specified.') immediately at ShardingManager.js:74, before any filesystem access.

Source

Thrown at packages/discord.js/src/sharding/ShardingManager.js:74

    super();
    const _options = {
      totalShards: 'auto',
      mode: 'process',
      respawn: true,
      silent: false,
      shardArgs: [],
      execArgv: [],
      token: process.env.DISCORD_TOKEN,
      ...options,
    };

    /**
     * Path to the shard script file
     *
     * @type {string}
     */
    this.file = file;
    if (!file) throw new DiscordjsError(ErrorCodes.ClientInvalidOption, 'File', 'specified.');
    if (!path.isAbsolute(file)) this.file = path.resolve(process.cwd(), file);
    // eslint-disable-next-line n/no-sync
    const stats = fs.statSync(this.file);
    if (!stats.isFile()) throw new DiscordjsError(ErrorCodes.ClientInvalidOption, 'File', 'a file');

    /**
     * List of shards this sharding manager spawns
     *
     * @type {string|number[]}
     */
    this.shardList = _options.shardList ?? 'auto';
    if (this.shardList !== 'auto') {
      if (!Array.isArray(this.shardList)) {
        throw new DiscordjsTypeError(ErrorCodes.ClientInvalidOption, 'shardList', 'an array.');
      }

      this.shardList = [...new Set(this.shardList)];
      if (this.shardList.length < 1) {

View on GitHub (pinned to a81ed8a306)

Solutions

1. Pass the absolute or relative path to your shard script as the first constructor argument
2. Ensure the config/env value supplying the path is defined before constructing ShardingManager
3. Add a startup check that fails early with a clear message if the path is missing

Example fix

// before
new ShardingManager(process.env.SHARD_FILE);
// after
if (!process.env.SHARD_FILE) throw new Error('SHARD_FILE env var is required');
const manager = new ShardingManager(process.env.SHARD_FILE);

const file = process.env.SHARD_FILE;
if (!file) throw new Error('Shard file path is required');
const manager = new ShardingManager(file);

const hasFile = (v) => typeof v === 'string' && v.trim().length > 0;

try {
  const manager = new ShardingManager(file);
} catch (err) {
  if (err.name === 'DiscordjsTypeError' && err.message.includes('File')) {
    console.error('Invalid shard file option:', err.message);
    process.exit(1);
  }
  throw err;
}

When it happens

Trigger: Calling new ShardingManager(''), new ShardingManager(), or passing a variable that resolves to undefined/null (e.g. process.env.SHARD_FILE not set) as the file argument.

Common situations: Config read from env or JSON where the shard file key is missing; refactored code where the file path constant was deleted; passing a value from an optional CLI argument without a default.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• ClientNotReady
• InvalidMissingScopes
• InvalidScopesWithPermissions
• InvalidElement
• ClientMissingIntents

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