{"record":{"id":"f80cbdae7fd1ac03","repo":"janhq/jan","slug":"unable-to-find-a-suitable-port-for-mlx-model","errorCode":null,"errorMessage":"Unable to find a suitable port for MLX model","messagePattern":"Unable to find a suitable port for MLX model","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"extensions/mlx-extension/src/index.ts","lineNumber":234,"sourceCode":"        id: modelId,\n        name: modelConfig.name ?? modelId,\n        providerId: this.provider,\n        port: 0,\n        sizeBytes: modelConfig.size_bytes ?? 0,\n        embedding: modelConfig.embedding ?? false,\n        capabilities: capabilities.length > 0 ? capabilities : undefined,\n      } as modelInfo)\n    }\n\n    return modelInfos\n  }\n\n  private async getRandomPort(): Promise<number> {\n    try {\n      return await invoke<number>('plugin:mlx|get_mlx_random_port')\n    } catch {\n      logger.error('Unable to find a suitable port for MLX server')\n      throw new Error('Unable to find a suitable port for MLX model')\n    }\n  }\n\n  override async load(\n    modelId: string,\n    overrideSettings?: any,\n    isEmbedding: boolean = false,\n    bypassAutoUnload: boolean = false\n  ): Promise<SessionInfo> {\n    const sInfo = await this.findSessionByModel(modelId)\n    if (sInfo) {\n      throw new Error('Model already loaded!')\n    }\n\n    if (this.loadingModels.has(modelId)) {\n      return this.loadingModels.get(modelId)!\n    }\n","sourceCodeStart":216,"sourceCodeEnd":252,"githubUrl":"https://github.com/janhq/jan/blob/7205d770c1e097c3daf35a911176410e93bc5564/extensions/mlx-extension/src/index.ts#L216-L252","documentation":"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.","triggerScenarios":"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.","commonSituations":"Systems with exhausted ephemeral port ranges or restrictive firewalls, broken/corrupted MLX plugin installation, or platform builds where the plugin command is not registered.","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"],"exampleFix":"// before\nawait mlx.load(modelId)\n// after\ntry {\n  await mlx.load(modelId)\n} catch (e) {\n  if (String(e).includes('suitable port')) {\n    logger.error('MLX port allocation failed; check firewall/port range', e)\n  }\n  throw e\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await mlx.load(modelId)\n} catch (e) {\n  if (String(e).includes('suitable port')) {\n    logger.error('MLX port allocation failed; check firewall/ephemeral range', e)\n  }\n  throw e\n}","preventionTips":["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"],"tags":["mlx","port-allocation","native","network"],"backgroundTag":"address-already-in-use","analyzedSha":"7205d770c1e097c3daf35a911176410e93bc5564","analyzedAt":"2026-09-17T14:27:30.100Z","contentChangedAt":"2026-09-17T14:27:30.100Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}