garrytan/gstack · error · Error

Shard count must be a positive integer. Received: ${shardCou

Error message

Shard count must be a positive integer. Received: ${shardCount}

What it means

assignFilesToShards() in scripts/test-free-shards.ts:208 requires shardCount to be a positive integer. Zero, negatives, non-integers, and NaN all throw. The function then builds N empty shards and distributes files via stableHash modulo shardCount.

Source

Thrown at scripts/test-free-shards.ts:208

    } else {
      safe.push(relativePath);
    }
  }
  return { safe, excluded };
}

export function stableHash(input: string): number {
  let hash = 0x811c9dc5;
  for (let index = 0; index < input.length; index += 1) {
    hash ^= input.charCodeAt(index);
    hash = Math.imul(hash, 0x01000193);
  }
  return hash >>> 0;
}

export function assignFilesToShards(files: string[], shardCount: number): string[][] {
  if (!Number.isInteger(shardCount) || shardCount <= 0) {
    throw new Error(`Shard count must be a positive integer. Received: ${shardCount}`);
  }

  const shards = Array.from({ length: shardCount }, () => [] as string[]);
  for (const file of files) {
    const shardIndex = stableHash(file) % shardCount;
    shards[shardIndex].push(file);
  }

  return shards
    .map(filesInShard => filesInShard.sort())
    .filter(filesInShard => filesInShard.length > 0);
}

export function buildShardArgs(files: string[]): string[] {
  return ['test', ...files, '--max-concurrency=1', `--timeout=${FREE_TEST_TIMEOUT_MS}`];
}

type CliOptions = {

View on GitHub (pinned to 94993f7401)

Solutions

1. Validate the input is a positive integer before calling
2. Clamp to at least 1 when deriving from file count
3. Default to DEFAULT_SHARD_COUNT when the value is unset or invalid

Example fix

// before
assignFilesToShards(files, 0)
// after
assignFilesToShards(files, DEFAULT_SHARD_COUNT)

if (!Number.isInteger(shardCount) || shardCount <= 0) {
  throw new Error(`Shard count must be a positive integer. Received: ${shardCount}`);
}

const isPositiveInteger = (n: number): boolean => Number.isInteger(n) && n > 0;

When it happens

Trigger: Passing 0 (e.g. when file set is tiny). Passing a float from a division. Passing NaN from Number.parseInt('abc'). Negative shard count.

Common situations: Reading shard count from an env var without validation. Math that yields 0 for small inputs. Unset CLI flag parsed to NaN.

Related errors

• Skill name is empty.
• Invalid skill name "${name}". Must be lowercase letters/digi
• stageSkill: files map is empty.
• Invalid file path in stageSkill: "${relPath}".
• commitSkill: staged path "${opts.stagedDir}" is not a direct

AI-assisted analysis of garrytan/gstack@94993f7401 (2026-08-12). Data as JSON: /api/errors/bcd6db7574e56186. Report an issue: GitHub.