What causes "Superblock not found: ${superBlock}" in freeCodeCamp/freeCodeCamp?

Set SHOW_UPCOMING_CHANGES=true in the environment if the superblock lives in SuperBlockStage.Upcoming.

freeCodeCamp/freeCodeCamp · error · Error

Superblock not found: ${superBlock}

Error message

Superblock not found: ${superBlock}

What it means

Thrown while the curriculum builder processes a superblock's blocks. processBlock calls getSuperOrder(superBlock), which builds an order map from generateSuperBlockList() — the superBlockStages config in packages/shared/src/config/curriculum.ts (the Upcoming stage is only included when SHOW_UPCOMING_CHANGES is true). If the superblock name is not a key in that map, superOrder is undefined and the build aborts: the superblock being built is not registered in the shared stage list, or it is an upcoming superblock while upcoming changes are hidden.

Source

Thrown at curriculum/src/build-superblock.ts:385

    { superBlock, order }: { superBlock: SuperBlocks; order: number }
  ) {
    const blockName = block.dashedName;
    log(`Processing block ${blockName} in superblock ${superBlock}`);

    // Check if block directory exists
    const blockContentDir = resolve(this.blockContentDir, blockName);
    if (!existsSync(blockContentDir)) {
      throw Error(`Block directory not found: ${blockContentDir}`);
    }

    if (block.isUpcomingChange && !SHOW_UPCOMING_CHANGES) {
      log(`Ignoring upcoming block ${blockName}`);
      return null;
    }

    const superOrder = getSuperOrder(superBlock);
    if (superOrder === undefined)
      throw Error(`Superblock not found: ${superBlock}`);
    const meta = {
      ...block,
      superOrder,
      superBlock,
      order,
      ...(block.chapter && { chapter: block.chapter }),
      ...(block.module && { module: block.module })
    };
    const isAudited = isAuditedSuperBlock(this.lang, superBlock as SuperBlocks);

    // Read challenges from directory
    const foundChallenges = await this.readBlockChallenges(
      blockName,
      meta,
      isAudited
    );
    log(`Found ${foundChallenges.length} challenge files in directory`);

View on GitHub (pinned to 4289125977)

Solutions

Set SHOW_UPCOMING_CHANGES=true in the environment if the superblock lives in SuperBlockStage.Upcoming.
Compare the name in the error with the SuperBlocks enum and use the exact dashed value (e.g. 'responsive-web-design-v9').
Register the new superblock in superBlockStages (packages/shared/src/config/curriculum.ts) and rebuild the shared config.

Example fix

// before: superblock only listed under [SuperBlockStage.Upcoming]
// after: also added to a visible stage
[SuperBlockStage.Core]: [
  SuperBlocks.RespWebDesignV9,
  SuperBlocks.JsV9,
  SuperBlocks.MyNewSuperBlock // added
]

Defensive patterns

Strategy: validation

Validate before calling

import { generateSuperBlockList } from '@freecodecamp/shared/config/curriculum';

const known = generateSuperBlockList({ showUpcomingChanges: true });
if (!known.includes(superBlock)) {
  throw new RangeError(
    `Unknown superblock '${superBlock}'. Valid values: ${known.join(', ')}`
  );
}

Type guard

import { generateSuperBlockList, SuperBlocks } from '@freecodecamp/shared/config/curriculum';

const KNOWN = new Set<string>(
  generateSuperBlockList({ showUpcomingChanges: true })
);
export const isSuperBlock = (sb: string): sb is SuperBlocks => KNOWN.has(sb);

Try / catch

try {
  await getChallengesForLang(lang, { superblock: [superBlock] });
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Superblock not found')) {
    // name not in superBlockStages, or SHOW_UPCOMING_CHANGES is off
    console.error(`${e.message} — check SHOW_UPCOMING_CHANGES and superBlockStages`);
    process.exitCode = 1;
  } else throw e;
}

Prevention

Type every superblock reference as the SuperBlocks enum, never plain string.
When adding a superblock, update superBlockStages in the same change that adds its structure JSON.
Set SHOW_UPCOMING_CHANGES=true in local/dev environments before building upcoming curriculum.

When it happens

Trigger: Building the curriculum (getChallengesForLang → buildCurriculum → SuperBlock.blocks → processBlock) with a filter or structure naming a superblock absent from superBlockStages; building a superblock that only exists in SuperBlockStage.Upcoming (full-stack-open, a2-spanish, ...) without SHOW_UPCOMING_CHANGES=true; a superblock structure or filter whose name does not match its SuperBlocks enum value.

Common situations: A new superblock was scaffolded (structure JSON, content directories) but never added to superBlockStages in packages/shared; local env missing SHOW_UPCOMING_CHANGES while the branch contains upcoming superblocks; a stale name left in scripts or filters after a superblock rename (e.g. v8 → v9).

Related errors

AI-assisted analysis of freeCodeCamp/freeCodeCamp@4289125977 (2026-08-24). Data as JSON: /api/errors/f14fd5eb7661e314. Report an issue: GitHub.