{"record":{"id":"7a12095945096518","repo":"jax-ml/jax","slug":"distributed-initialize-should-only-be-called-once","errorCode":null,"errorMessage":"distributed.initialize should only be called once.","messagePattern":"distributed\\.initialize should only be called once\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"jax/_src/distributed.py","lineNumber":191,"sourceCode":"      proxy_vars = [key for key in os.environ.keys()\n                    if '_proxy' in key.lower()]\n\n    if len(proxy_vars) > 0:\n      vars = \" \".join(proxy_vars) + \". \"\n      warning = (\n        f'JAX detected proxy variable(s) in the environment as distributed setup: {vars}'\n        'On some systems, this may cause a hang of distributed.initialize and '\n        'you may need to unset these ENV variable(s)'\n      )\n      logger.warning(warning)\n\n    mtls_kwargs = _get_mtls_kwargs(\n        mtls_cert_file, mtls_key_file, mtls_ca_file, mtls_peer_uri_prefix,\n        verify_secure_credentials)\n\n    if process_id == 0:\n      if self.service is not None:\n        raise RuntimeError('distributed.initialize should only be called once.')\n      logger.info(\n          'Starting JAX distributed service on %s', coordinator_bind_address\n      )\n      self.service = _jax.get_distributed_runtime_service(\n          coordinator_bind_address,\n          num_processes,\n          heartbeat_timeout=heartbeat_timeout_seconds,\n          shutdown_timeout=shutdown_timeout_seconds,\n          recoverable=_ENABLE_RECOVERABILITY.value,\n          **mtls_kwargs,\n      )\n\n    self.num_processes = num_processes\n\n    if self.client is not None:\n      raise RuntimeError('distributed.initialize should only be called once.')\n\n    self.client = _jax.get_distributed_runtime_client(","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/distributed.py#L173-L209","documentation":"Only process 0 hosts the distributed coordination service, and it may host it exactly once per process. Calling jax.distributed.initialize again while self.service is already set raises this RuntimeError.","triggerScenarios":"Calling jax.distributed.initialize() twice in the same Python process on rank 0 — e.g. a training script that re-initializes between runs, or library + user code both initializing.","commonSituations":"Notebook/REPL workflows rerunning the init cell; frameworks (e.g. Flax/JAX serving stacks) that initialize internally while user code also calls it; test suites reusing the process.","solutions":["Guard with the global state: if jax._src.distributed.global_state.service is None: initialize(...) — or simply call shutdown() before re-initializing","Call jax.distributed.shutdown() before a second initialize in rerunnable scripts/notebooks","Initialize once at process startup (entrypoint) and let libraries detect existing state"],"exampleFix":"# before\njax.distributed.initialize(...)  # run twice -> RuntimeError\n# after\nif jax.distributed.process_id == 0 and not jax._src.distributed.global_state.service:\n    jax.distributed.initialize(...)\n# or: jax.distributed.shutdown(); jax.distributed.initialize(...)","handlingStrategy":"try-catch","validationCode":"import jax._src.distributed as dist\nalready = dist.global_state.service is not None\nif not already:\n    jax.distributed.initialize(...)","typeGuard":null,"tryCatchPattern":"try:\n    jax.distributed.initialize(...)\nexcept RuntimeError as e:\n    if 'only be called once' in str(e):\n        pass  # already initialized; safe to continue\n    else:\n        raise","preventionTips":["Initialize once at process entrypoint","Call jax.distributed.shutdown() before re-init in notebooks","Guard init behind an idempotent helper"],"tags":["jax","distributed","double-init","lifecycle"],"backgroundTag":"double-initialization","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}