{"record":{"id":"6a59b7f2e330d35c","repo":"Crosstalk-Solutions/project-nomad","slug":"pmtiles-extract-for-world-basemap-failed-err-me","errorCode":null,"errorMessage":"pmtiles extract for world basemap failed: ${err.message}. stderr: ${err.stderr ?? ''}","messagePattern":"pmtiles extract for world basemap failed: (.+?)\\. stderr: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"admin/app/services/map_service.ts","lineNumber":487,"sourceCode":"    const args = buildPmtilesExtractArgs({\n      sourceUrl: info.url,\n      outputFilepath: filepath,\n      maxzoom: WORLD_BASEMAP_MAX_ZOOM,\n      downloadThreads: 4,\n    })\n\n    logger.info(\n      `[MapService] Extracting world basemap (z0-${WORLD_BASEMAP_MAX_ZOOM}) from ${info.url}`\n    )\n    try {\n      await execFileAsync(PMTILES_BINARY_PATH, args, {\n        timeout: WORLD_BASEMAP_EXTRACT_TIMEOUT_MS,\n        maxBuffer: DRY_RUN_MAX_BUFFER,\n      })\n      this.worldBasemapReady = true\n    } catch (err: any) {\n      await deleteFileIfExists(filepath)\n      throw new Error(\n        `pmtiles extract for world basemap failed: ${err.message}. stderr: ${err.stderr ?? ''}`\n      )\n    }\n  }\n\n  private async checkBaseAssetsExist(useCache: boolean = true): Promise<boolean> {\n    // Return cached result if available and caching is enabled\n    if (useCache && this.baseAssetsExistCache !== null) {\n      return this.baseAssetsExistCache\n    }\n\n    await ensureDirectoryExists(this.baseDirPath)\n\n    const baseStylePath = join(this.baseDirPath, this.baseStylesFile)\n    const basemapsAssetsPath = join(this.baseDirPath, this.basemapsAssetsDir)\n\n    const [baseStyleExists, basemapsAssetsExists] = await Promise.all([\n      getFileStatsIfExists(baseStylePath),","sourceCodeStart":469,"sourceCodeEnd":505,"githubUrl":"https://github.com/Crosstalk-Solutions/project-nomad/blob/0bd1c6f4f9888d577fe232de06ac144bb8337131/admin/app/services/map_service.ts#L469-L505","documentation":"Setting up the world basemap runs a 'pmtiles extract' subprocess (with a timeout and buffer cap) to carve a smaller world basemap out of a downloaded source. If the child process errors, times out, or exceeds maxBuffer, the partial output file is deleted and this error wraps the subprocess message and stderr.","triggerScenarios":"The pmtiles CLI not installed or not on PATH; the extract exceeding WORLD_BASEMAP_EXTRACT_TIMEOUT_MS; output exceeding DRY_RUN_MAX_BUFFER; corrupted source .pmtiles; disk full during extract.","commonSituations":"Docker images missing the pmtiles binary; low-memory containers hitting the buffer cap; slow disk/network making extraction exceed the timeout; truncated source download from a flaky CDN.","solutions":["Read the embedded stderr in the message — it usually names the exact cause (ENOENT for missing binary, memory/disk messages, etc.)","Verify the pmtiles CLI is installed and on PATH: pmtiles --version","Increase WORLD_BASEMAP_EXTRACT_TIMEOUT_MS / DRY_RUN_MAX_BUFFER on slow or memory-constrained hosts","Delete the source .pmtiles so it re-downloads, in case the input is corrupted"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"import { execFile } from 'child_process'\nconst ok = await new Promise<boolean>(res => execFile('pmtiles', ['--version'], t => res(!t)))\nif (!ok) throw new Error('pmtiles CLI not available')","typeGuard":null,"tryCatchPattern":"try { await mapService.ensureWorldBasemap() } catch (e) { if (e instanceof Error && e.message.includes('pmtiles extract')) { logger.error(e.message) /* parse stderr, fix env, retry once */ } throw e }","preventionTips":["Verify pmtiles CLI presence in container health checks","Provision the world basemap during build/deploy, not on first request","Tune extract timeout/maxBuffer for your host's disk and memory","Free disk space monitoring on the storage volume"],"tags":["subprocess","pmtiles","timeout","extract"],"backgroundTag":"subprocess-extract-failed","analyzedSha":"0bd1c6f4f9888d577fe232de06ac144bb8337131","analyzedAt":"2026-08-27T05:34:15.424Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}