Crosstalk-Solutions/project-nomad · error · Error

Base map assets are missing and could not be downloaded. Ple

Error message

Base map assets are missing and could not be downloaded. Please check your connection and try again.

What it means

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.

Source

Thrown at admin/app/services/map_service.ts:280

    }

    const existing = await RunDownloadJob.getActiveByUrl(url)
    if (existing) {
      throw new Error(`Download already in progress for URL ${url}`)
    }

    const filename = url.split('/').pop()
    if (!filename) {
      throw new Error('Could not determine filename from URL')
    }

    const filepath = join(process.cwd(), this.mapStoragePath, 'pmtiles', filename)


    // First, ensure base assets are present - regions depend on them
    const baseAssetsExist = await this.ensureBaseAssets()
    if (!baseAssetsExist) {
      throw new Error(
        'Base map assets are missing and could not be downloaded. Please check your connection and try again.'
      )
    }

    // Parse resource metadata
    const parsedFilename = CollectionManifestService.parseMapFilename(filename)
    const resourceMetadata = parsedFilename
      ? { resource_id: parsedFilename.resource_id, version: parsedFilename.version, collection_ref: null }
      : undefined

    // Dispatch background job
    const result = await RunDownloadJob.dispatch({
      url,
      filepath,
      timeout: 30000,
      allowedMimeTypes: PMTILES_MIME_TYPES,
      forceNew: true,
      filetype: 'map',

View on GitHub (pinned to 0bd1c6f4f9)

Solutions

1. Check network connectivity from the server to the protomaps builds URL (curl the URL from logs)
2. Verify the storage/maps directory exists and is writable by the process user
3. Pre-run ensureBaseAssets()/ensureWorldBasemap() during deployment or startup so failures surface early, and retry downloadRemote once assets are in place
4. If permanently offline, manually place the world basemap .pmtiles and base assets into storage/maps

Example fix

// before
await mapService.downloadRemote(url)

// after
const ok = await mapService.ensureBaseAssets()
if (!ok) throw new Error('run provisioning step first')
await mapService.downloadRemote(url)

if (!(await mapService.checkBaseAssetsExist(false))) {
  await mapService.ensureBaseAssets()
}
if (!(await mapService.checkBaseAssetsExist())) throw new Error('provision storage/maps first')
await mapService.downloadRemote(url)

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 }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Base map assets are missing from storage/maps
• Storage drive not available: cannot write to ${STORAGE_BASE}
• HTTP ${resp.status} from ${MANIFEST_URL}
• No internet — connect to download FDA drug data. (${msg})
• Failed to download tar file

AI-assisted analysis of Crosstalk-Solutions/project-nomad@0bd1c6f4f9 (2026-08-27). Data as JSON: /api/errors/80df40fee0e74651. Report an issue: GitHub.