{"record":{"id":"80df40fee0e74651","repo":"Crosstalk-Solutions/project-nomad","slug":"base-map-assets-are-missing-and-could-not-be-downl","errorCode":null,"errorMessage":"Base map assets are missing and could not be downloaded. Please check your connection and try again.","messagePattern":"Base map assets are missing and could not be downloaded\\. Please check your connection and try again\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"admin/app/services/map_service.ts","lineNumber":280,"sourceCode":"    }\n\n    const existing = await RunDownloadJob.getActiveByUrl(url)\n    if (existing) {\n      throw new Error(`Download already in progress for URL ${url}`)\n    }\n\n    const filename = url.split('/').pop()\n    if (!filename) {\n      throw new Error('Could not determine filename from URL')\n    }\n\n    const filepath = join(process.cwd(), this.mapStoragePath, 'pmtiles', filename)\n\n\n    // First, ensure base assets are present - regions depend on them\n    const baseAssetsExist = await this.ensureBaseAssets()\n    if (!baseAssetsExist) {\n      throw new Error(\n        'Base map assets are missing and could not be downloaded. Please check your connection and try again.'\n      )\n    }\n\n    // Parse resource metadata\n    const parsedFilename = CollectionManifestService.parseMapFilename(filename)\n    const resourceMetadata = parsedFilename\n      ? { resource_id: parsedFilename.resource_id, version: parsedFilename.version, collection_ref: null }\n      : undefined\n\n    // Dispatch background job\n    const result = await RunDownloadJob.dispatch({\n      url,\n      filepath,\n      timeout: 30000,\n      allowedMimeTypes: PMTILES_MIME_TYPES,\n      forceNew: true,\n      filetype: 'map',","sourceCodeStart":262,"sourceCodeEnd":298,"githubUrl":"https://github.com/Crosstalk-Solutions/project-nomad/blob/0bd1c6f4f9888d577fe232de06ac144bb8337131/admin/app/services/map_service.ts#L262-L298","documentation":"downloadRemote requires the base map assets (under storage/maps) to exist before downloading region files, because regional styles reference the base sprite/glyph/world basemap. ensureBaseAssets() attempts to set them up (including downloading the world basemap); if after that attempt the assets still are not present, this error is thrown.","triggerScenarios":"Calling downloadRemote when storage/maps is empty/corrupted AND ensureBaseAssets fails — typically because the machine has no outbound network access to fetch the protomaps world basemap, or a previous extract failed and left the assets missing.","commonSituations":"Offline or firewalled servers; misconfigured storage path (mapStoragePath pointing to an unwritable/nonexistent directory); a previous failed download left partial state; proxy/DNS issues blocking the protomaps builds CDN.","solutions":["Check network connectivity from the server to the protomaps builds URL (curl the URL from logs)","Verify the storage/maps directory exists and is writable by the process user","Pre-run ensureBaseAssets()/ensureWorldBasemap() during deployment or startup so failures surface early, and retry downloadRemote once assets are in place","If permanently offline, manually place the world basemap .pmtiles and base assets into storage/maps"],"exampleFix":"// before\nawait mapService.downloadRemote(url)\n\n// after\nconst ok = await mapService.ensureBaseAssets()\nif (!ok) throw new Error('run provisioning step first')\nawait mapService.downloadRemote(url)","handlingStrategy":"retry","validationCode":"if (!(await mapService.checkBaseAssetsExist(false))) {\n  await mapService.ensureBaseAssets()\n}\nif (!(await mapService.checkBaseAssetsExist())) throw new Error('provision storage/maps first')\nawait mapService.downloadRemote(url)","typeGuard":null,"tryCatchPattern":"try { await mapService.downloadRemote(url) } catch (e) { if (e instanceof Error && e.message.startsWith('Base map assets')) { await delay(5000); await mapService.ensureBaseAssets(); return mapService.downloadRemote(url) } throw e }","preventionTips":["Run ensureBaseAssets() during deployment/startup, not lazily on first request","Monitor storage/maps existence in health checks","Alert on outbound network failures to the protomaps CDN"],"tags":["network","storage","pmtiles","asset-provisioning"],"backgroundTag":"asset-download-failed","analyzedSha":"0bd1c6f4f9888d577fe232de06ac144bb8337131","analyzedAt":"2026-08-27T05:34:15.424Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}