koala73/worldmonitor · error · ConvexError

COUNTRY_LOCKS_NOT_SEEDED

COUNTRY_LOCKS_NOT_SEEDED

Error message

COUNTRY_LOCKS_NOT_SEEDED

What it means

Infrastructure sentinel from readCountryLockOrThrow: no followedCountriesCountryLocks row exists for the country being followed (logged with breadcrumb before throwing). Country lock rows are seeded alongside shards; a missing lock means seeding is incomplete or the country is outside the seeded set.

Source

Thrown at convex/followedCountries.ts:126

  await ctx.db.patch(shard._id, { lastTouchedAt: Date.now() });
}

async function readCountryLockOrThrow(
  ctx: MutationCtx,
  country: string,
): Promise<Doc<"followedCountriesCountryLocks">> {
  const lock = await ctx.db
    .query("followedCountriesCountryLocks")
    .withIndex("by_country", (q) => q.eq("country", country))
    .first();
  if (!lock) {
    console.error(
      JSON.stringify({
        breadcrumb: "followed_countries_country_locks_not_seeded",
        country,
      }),
    );
    throw new ConvexError({ kind: "COUNTRY_LOCKS_NOT_SEEDED", country });
  }
  return lock;
}

async function touchCountryLock(
  ctx: MutationCtx,
  lock: Doc<"followedCountriesCountryLocks">,
): Promise<void> {
  await ctx.db.patch(lock._id, { lastTouchedAt: Date.now() });
}

/**
 * Read the per-user serialization row for `userId`. Returns the row (if
 * exists) and the denormalized count (0 if no row). Every mutation that
 * mutates `followedCountries` for the user MUST call this AND patch/insert
 * the row at the end — that read+write pair is what triggers Convex
 * per-document OCC retry under same-user concurrency.
 *

View on GitHub (pinned to eeab0a219f)

Solutions

1. Run the seed script or cron to create the missing country lock rows
2. If the country code itself is invalid, INVALID_COUNTRY should fire first — check why an unseeded country reached the lock read
3. Alert on the country_locks_not_seeded breadcrumb to catch seed drift

When it happens

Trigger: Thrown at convex/followedCountries.ts:126 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/4d23fcec38ddf503. Report an issue: GitHub.