koala73/worldmonitor · error · ConvexError

SHARDS_NOT_SEEDED

SHARDS_NOT_SEEDED

Error message

SHARDS_NOT_SEEDED

What it means

Infrastructure sentinel from readShardOrThrow: no followedCountriesShards row exists for the user's shard (userIdToShard). Shards are pre-created by deploy seeding plus the daily _seedShards cron, so hitting this is an operator or deployment error — it is logged loudly (breadcrumb JSON) for on-call before throwing.

Source

Thrown at convex/followedCountries.ts:93

  ctx: MutationCtx,
  userId: string,
): Promise<Doc<"followedCountriesShards">> {
  const shardId = userIdToShard(userId);
  const shard = await ctx.db
    .query("followedCountriesShards")
    .withIndex("by_shard", (q) => q.eq("shardId", shardId))
    .first();
  if (!shard) {
    // Operator error — should never happen in production after deploy +
    // the daily `_seedShards` cron. Logged loudly so on-call sees it.
    console.error(
      JSON.stringify({
        breadcrumb: "followed_countries_shards_not_seeded",
        shardId,
        shardCount: SHARD_COUNT,
      }),
    );
    throw new ConvexError({ kind: "SHARDS_NOT_SEEDED", shardId });
  }
  return shard;
}

/**
 * Patch the shard row's `lastTouchedAt` — the OCC-serializing write that
 * pairs with `readShardOrThrow`. MUST run on the success path AFTER all
 * other writes; on any throw, Convex aborts the entire transaction and
 * the patch is rolled back along with everything else.
 */
async function touchShard(
  ctx: MutationCtx,
  shard: Doc<"followedCountriesShards">,
): Promise<void> {
  await ctx.db.patch(shard._id, { lastTouchedAt: Date.now() });
}

async function readCountryLockOrThrow(

View on GitHub (pinned to eeab0a219f)

Solutions

1. Run the shard-seed script or the _seedShards cron to create the missing shard rows
2. Verify SHARD_COUNT matches between seeding and lookup — a mismatch makes some shards permanently missing
3. Alert on the followed_countries_shards_not_seeded breadcrumb so on-call catches seed drift early

When it happens

Trigger: Thrown at convex/followedCountries.ts:93 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of koala73/worldmonitor@eeab0a219f (2026-08-21). Data as JSON: /api/errors/f5e700a4f7c4f4a2. Report an issue: GitHub.