koala73/worldmonitor · error · BboxValidationError

bbox invalid: each dimension must be ≤ ${MAX_BBOX_DEGREES} d

Error message

bbox invalid: each dimension must be ≤ ${MAX_BBOX_DEGREES} degrees

What it means

Bbox size validation in extractAndValidateBbox: the box is geometrically valid but one or both dimensions exceed MAX_BBOX_DEGREES. The cap bounds query cost and result size for vessel snapshots; requests must zoom in rather than scan a hemisphere.

Source

Thrown at server/worldmonitor/maritime/v1/get-vessel-snapshot.ts:320

function extractAndValidateBbox(req: GetVesselSnapshotRequest): { swLat: number; swLon: number; neLat: number; neLon: number } | null {
  const sw = { lat: Number(req.swLat), lon: Number(req.swLon) };
  const ne = { lat: Number(req.neLat), lon: Number(req.neLon) };
  // All zeroes (the default for unset proto doubles) → no bbox.
  if (sw.lat === 0 && sw.lon === 0 && ne.lat === 0 && ne.lon === 0) {
    return null;
  }
  if (!isValidLatLon(sw.lat, sw.lon)) {
    throw new BboxValidationError('sw corner outside lat/lon domain (-90..90 / -180..180)');
  }
  if (!isValidLatLon(ne.lat, ne.lon)) {
    throw new BboxValidationError('ne corner outside lat/lon domain (-90..90 / -180..180)');
  }
  if (sw.lat > ne.lat || sw.lon > ne.lon) {
    throw new BboxValidationError('sw corner must be south-west of ne corner');
  }
  if (ne.lat - sw.lat > MAX_BBOX_DEGREES || ne.lon - sw.lon > MAX_BBOX_DEGREES) {
    throw new BboxValidationError(`each dimension must be ≤ ${MAX_BBOX_DEGREES} degrees`);
  }
  return { swLat: sw.lat, swLon: sw.lon, neLat: ne.lat, neLon: ne.lon };
}

export async function getVesselSnapshot(
  _ctx: ServerContext,
  req: GetVesselSnapshotRequest,
): Promise<GetVesselSnapshotResponse> {
  try {
    const bbox = extractAndValidateBbox(req);
    const snapshot = await fetchVesselSnapshot(
      Boolean(req.includeCandidates),
      Boolean(req.includeTankers),
      bbox,
    );
    return {
      snapshot,
      fetchedAt: snapshot?.snapshotAt ?? 0,

View on GitHub (pinned to eeab0a219f)

Solutions

1. Reduce the bounding box dimensions to at most MAX_BBOX_DEGREES per side
2. Zoom the map in and request snapshots per visible region instead of one giant box

When it happens

Trigger: Thrown at server/worldmonitor/maritime/v1/get-vessel-snapshot.ts:320 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/57ffc628eb3dcd28. Report an issue: GitHub.