What causes "Unable to find a suitable port for MLX model" in janhq/jan?

Check logs for the underlying native error logged just before this throw

Unable to find a suitable port for MLX model

Error message

Unable to find a suitable port for MLX model

What it means

The MLX extension's getRandomPort asks the Tauri plugin (plugin:mlx|get_mlx_random_port) for a free OS port to run the MLX server; if the native side fails it logs and throws this message. Without a port the model server cannot be started.

Solutions

Check logs for the underlying native error logged just before this throw
Free up ports / check ephemeral port range and firewall restrictions
Reinstall the app/extension so the mlx Tauri plugin is correctly registered
Restart the machine to clear port exhaustion
Report the logged root cause if ports are clearly available

Example fix

// before
await mlx.load(modelId)
// after
try {
  await mlx.load(modelId)
} catch (e) {
  if (String(e).includes('suitable port')) {
    logger.error('MLX port allocation failed; check firewall/port range', e)
  }
  throw e
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await mlx.load(modelId)
} catch (e) {
  if (String(e).includes('suitable port')) {
    logger.error('MLX port allocation failed; check firewall/ephemeral range', e)
  }
  throw e
}

Prevention

Check firewall/ephemeral port configuration on constrained systems
Reinstall the app if the mlx Tauri plugin appears missing
Restart the machine if port exhaustion is suspected
Always read the logged native error preceding this throw

When it happens

Trigger: Calling load (which requests a port) when the OS has no free port available, the Tauri mlx plugin is missing/failing, or the native port-probe command errors.

Common situations: Systems with exhausted ephemeral port ranges or restrictive firewalls, broken/corrupted MLX plugin installation, or platform builds where the plugin command is not registered.

Related errors

AI-assisted analysis of janhq/jan@7205d770c1 (2026-09-17). Data as JSON: /api/errors/f80cbdae7fd1ac03. Report an issue: GitHub.

Appendix: source

Thrown at extensions/mlx-extension/src/index.ts:234

        id: modelId,
        name: modelConfig.name ?? modelId,
        providerId: this.provider,
        port: 0,
        sizeBytes: modelConfig.size_bytes ?? 0,
        embedding: modelConfig.embedding ?? false,
        capabilities: capabilities.length > 0 ? capabilities : undefined,
      } as modelInfo)
    }

    return modelInfos
  }

  private async getRandomPort(): Promise<number> {
    try {
      return await invoke<number>('plugin:mlx|get_mlx_random_port')
    } catch {
      logger.error('Unable to find a suitable port for MLX server')
      throw new Error('Unable to find a suitable port for MLX model')
    }
  }

  override async load(
    modelId: string,
    overrideSettings?: any,
    isEmbedding: boolean = false,
    bypassAutoUnload: boolean = false
  ): Promise<SessionInfo> {
    const sInfo = await this.findSessionByModel(modelId)
    if (sInfo) {
      throw new Error('Model already loaded!')
    }

    if (this.loadingModels.has(modelId)) {
      return this.loadingModels.get(modelId)!
    }

View on GitHub (pinned to 7205d770c1)