agalwood/Motrix · warning · AppError

GeoIPSourceUnsupported

GeoIPSourceUnsupported

Error message

MaxMind official source is not yet supported (Phase 2.1).

What it means

Thrown by the GeoIP manager when the configured source is 'maxmind' but resolveDownloadUrl(settings) returns no usable URL — the official MaxMind source requires an account/license key and is explicitly marked unimplemented (Phase 2.1). The manager stores the message as lastError, emits status, and throws GeoIPSourceUnsupported.

Source

Thrown at src/core/geoip/geo-ip-manager.ts:176

    if (Date.now() - s.lastUpdatedAt < intervalMs) return
    if (this.isDownloading) return
    log.info({ source: s.source }, 'GeoIP auto-update due')
    await this.triggerUpdate().catch(() => {
      // Errors already recorded in lastError + status event.
    })
  }

  private async runUpdate(): Promise<GeoIPStatus> {
    const settings = this.getSettings()
    const url = resolveDownloadUrl(settings)
    if (!url) {
      const message =
        settings.source === 'maxmind'
          ? 'MaxMind official source is not yet supported (Phase 2.1).'
          : 'No download URL configured for the selected source.'
      this.lastError = message
      this.emitStatus()
      throw new AppError(ErrorCode.GeoIPSourceUnsupported, message)
    }

    this.isDownloading = true
    this.lastError = null
    this.emitStatus()

    const onProgress: ProgressListener = (progress) => {
      this.eventBus.emit(Events.GeoIPUpdateProgress, progress)
    }

    try {
      const result = await this.downloader.download(
        url,
        this.dbPath,
        onProgress
      )
      await this.service.reload(this.dbPath)
      this.currentSizeBytes = result.sizeBytes

View on GitHub (pinned to 1a708ee577)

Solutions

1. Switch the GeoIP source to a supported mirror (e.g. the default free GeoLite mirror) until MaxMind support ships.
2. In settings, set geoip.source away from 'maxmind'.
3. Provide a license key + host URL only once the MaxMind integration is implemented (track Phase 2.1).
4. Reset GeoIP settings to defaults to clear the stale 'maxmind' selection.

Example fix

// before
const url = resolveDownloadUrl(settings)
if (!url) {
  const message = settings.source === 'maxmind' ? 'MaxMind official source is not yet supported (Phase 2.1).' : 'No download URL configured for the selected source.'
  throw new AppError(ErrorCode.GeoIPSourceUnsupported, message)
}

// after — fail fast at settings time so users cannot select an unsupported source
if (settings.source === 'maxmind') {
  throw new AppError(ErrorCode.GeoIPSourceUnsupported, 'MaxMind official source is not yet supported (Phase 2.1). Use a supported mirror.')
}

// Reject unsupported sources at settings time, before runUpdate is ever called.
function assertGeoIpSourceSupported(source: string) {
  if (source === 'maxmind') {
    throw new AppError(ErrorCode.GeoIPSourceUnsupported, 'MaxMind official source is not yet supported (Phase 2.1).')
  }
}

const SUPPORTED_SOURCES = new Set(['mirror', 'custom' /* ...actual supported values */ ])
function isSupportedSource(s: string): s is (typeof SUPPORTED_SOURCES extends Set<infer T> ? T : never) {
  return SUPPORTED_SOURCES.has(s)
}

try {
  await manager.update()
} catch (err) {
  if (err instanceof AppError && err.code === ErrorCode.GeoIPSourceUnsupported && /MaxMind/.test(err.message)) {
    // switch source to a supported mirror in settings, then retry
  } else throw err
}

When it happens

Trigger: runUpdate() is called with settings.source === 'maxmind'. resolveDownloadUrl returns null/undefined because the MaxMind path is not yet wired up, so the unsupported-source branch is taken.

Common situations: A user or config preset selected the MaxMind source before the integration shipped; an old config persisted 'maxmind' as the source after an upgrade/downgrade; a defaults file sets maxmind as the preferred source.

Related errors

• GeoIPDownloadFailed
• GeoIPDatabaseInvalid
• plugin.lifecycle.secrets_seed_missing
• plugin.lifecycle.secrets_seed_missing

AI-assisted analysis of agalwood/Motrix@1a708ee577 (2026-08-12). Data as JSON: /api/errors/69902c48a0c5f312. Report an issue: GitHub.