{"record":{"id":"f59b569ca1ffc88f","repo":"apache/beam","slug":"error-upgrading-setuptools","errorCode":null,"errorMessage":"error upgrading setuptools","messagePattern":"error upgrading setuptools","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"sdks/go/pkg/beam/core/runtime/xlangx/expansionx/download.go","lineNumber":471,"sourceCode":"\tbeamPackage := fmt.Sprintf(\"apache_beam[gcp,aws,azure,dataframe]==%s\", core.SdkVersion)\n\tvenvDir := filepath.Join(\n\t\tcacheDir, \"venvs\",\n\t\tfmt.Sprintf(\"py-%s-beam-%s-%s\", py, core.SdkVersion, strings.Join(extraPackages, \";\")),\n\t)\n\tvenvPython := filepath.Join(venvDir, \"bin\", \"python\")\n\n\tif _, err := os.Stat(venvPython); err != nil {\n\t\terr := exec.Command(py, \"-m\", \"venv\", venvDir).Run()\n\t\tif err != nil {\n\t\t\treturn \"\", errors.Wrap(err, \"error creating new virtual environment for python expansion service\")\n\t\t}\n\t\terr = exec.Command(venvPython, \"-m\", \"pip\", \"install\", \"--upgrade\", \"pip\").Run()\n\t\tif err != nil {\n\t\t\treturn \"\", errors.Wrap(err, \"error upgrading pip\")\n\t\t}\n\t\terr = exec.Command(venvPython, \"-m\", \"pip\", \"install\", \"--upgrade\", \"setuptools\").Run()\n\t\tif err != nil {\n\t\t\treturn \"\", errors.Wrap(err, \"error upgrading setuptools\")\n\t\t}\n\t\terr = exec.Command(venvPython, \"-m\", \"pip\", \"install\", beamPackage, \"pyparsing==2.4.2\").Run()\n\t\tif err != nil {\n\t\t\treturn \"\", errors.Wrap(err, fmt.Sprintf(\"error installing beam package: %v\", beamPackage))\n\t\t}\n\t\tif len(extraPackages) > 0 {\n\t\t\tcmd := []string{\"-m\", \"pip\", \"install\"}\n\t\t\tcmd = append(cmd, extraPackages...)\n\t\t\terr = exec.Command(venvPython, cmd...).Run()\n\t\t\tif err != nil {\n\t\t\t\treturn \"\", errors.Wrap(err, \"error installing dependencies\")\n\t\t\t}\n\t\t}\n\t\terr = exec.Command(venvPython, \"-c\", \"import apache_beam\").Run()\n\t\tif err != nil {\n\t\t\treturn \"\", errors.Wrap(err, \"apache beam installation failed in virtualenv\")\n\t\t}\n\t}","sourceCodeStart":453,"sourceCodeEnd":489,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/go/pkg/beam/core/runtime/xlangx/expansionx/download.go#L453-L489","documentation":"Raised in expansionx.SetUpPythonEnvironment when `pip install --upgrade setuptools` fails inside the Python expansion service virtualenv. Environment setup is aborted and no venv python path is returned.","triggerScenarios":"startPythonExpansionService -> SetUpPythonEnvironment where the setuptools upgrade returns non-zero, typically network/PyPI access problems or an incompatible wheel for the platform/Python version.","commonSituations":"No internet or blocked PyPI; very old/new Python with no compatible setuptools wheel; disk space exhaustion; corporate mirror rejecting the package.","solutions":["Check network access to PyPI and configure proxy env vars if behind a corporate proxy","Run `<venv>/bin/python -m pip install --upgrade setuptools` manually to see the underlying output","Pin a setuptools version compatible with the interpreter if a wheel resolution error occurs","Free disk space and confirm the venv directory is writable"],"exampleFix":"// before\n// error upgrading setuptools\n// after: pin compatible version\n./venv/bin/python -m pip install \"setuptools<60\"","handlingStrategy":"validation","validationCode":"if err := exec.Command(venvPython, \"-m\", \"pip\", \"install\", \"--upgrade\", \"setuptools\").Run(); err != nil {\n    return fmt.Errorf(\"setuptools upgrade failed: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"python, err := expansionx.SetUpPythonEnvironment(ctx, py, pkg, extras)\nif err != nil && strings.Contains(err.Error(), \"error upgrading setuptools\") {\n    return fmt.Errorf(\"pip/setuptools bootstrap failed; check network and Python compatibility: %w\", err)\n}","preventionTips":["Ensure network access to PyPI and enough disk space","Use a Python version with prebuilt setuptools wheels","Pre-provision the venv manually once, then reuse the cached environment"],"tags":["python","pip","setuptools","virtualenv"],"backgroundTag":"missing-dependency","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}