Crosstalk-Solutions/project-nomad · error · Error

Failed to dispatch download job

Error message

Failed to dispatch download job

What it means

downloadRemote delegates the actual fetch to a download job system (dispatchDownloadJob-like call with forceNew and resourceMetadata). If that dispatcher returns a result without a job object, the service cannot proceed and throws this error, meaning the job queue accepted the request but produced no job record.

Source

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

    // 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',
      resourceMetadata,
    })

    if (!result.job) {
      throw new Error('Failed to dispatch download job')
    }

    logger.info(`[MapService] Dispatched download job ${result.job.id} for URL ${url}`)

    return {
      filename,
      jobId: result.job?.id,
    }
  }

  async downloadRemotePreflight(
    url: string
  ): Promise<{ filename: string; size: number } | { message: string }> {
    try {
      assertNotPrivateUrl(url)
      const parsed = new URL(url)
      if (!parsed.pathname.endsWith('.pmtiles')) {
        throw new Error(`Invalid PMTiles file URL: ${url}. URL must end with .pmtiles`)

View on GitHub (pinned to 0bd1c6f4f9)

Solutions

  1. Inspect server logs immediately before this line for the dispatcher's underlying error
  2. Verify the job queue backend (DB/Redis) is up and the run_download_jobs table exists (run migrations)
  3. Reproduce by calling downloadRemote after confirming dispatch works for other filetypes
  4. Retry the call once transient queue issues are resolved
Defensive patterns

Strategy: try-catch

Try / catch

try { const res = await mapService.downloadRemote(url) } catch (e) { if (e instanceof Error && e.message === 'Failed to dispatch download job') { /* inspect job queue backend health, then surface to user */ } throw e }

Prevention

When it happens

Trigger: Calling downloadRemote when the job dispatch layer fails internally — e.g. database/queue unavailable, job creation rejected, or the dispatcher returns { job: null } due to an unexpected filetype/metadata combination.

Common situations: Job queue (DB/Redis) not running or misconfigured; migrations for the run-download-jobs table not applied; version mismatch between map_service and the job dispatcher API; concurrent dispatch hitting a unique constraint that swallows the job.

Related errors

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