{"record":{"id":"8c416c04c9c877ba","repo":"apache/beam","slug":"protoc-returned-non-zero-status-see-logs-for-details-s","errorCode":null,"errorMessage":"Protoc returned non-zero status (see logs for details): %s","messagePattern":"Protoc returned non-zero status \\(see logs for details\\): (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"sdks/python/gen_protos.py","lineNumber":496,"sourceCode":"      [sys.executable] +  # expecting to be called from command line\n      ['--proto_path=%s' % builtin_protos] +\n      ['--proto_path=%s' % d\n      for d in proto_dirs] + ['--python_out=%s' % PYTHON_OUTPUT_PATH] +\n      ['--plugin=protoc-gen-mypy=%s' % protoc_gen_mypy] +\n      # new version of mypy-protobuf converts None to zero default value\n      # and remove Optional from the param type annotation. This causes\n      # some mypy errors. So to mitigate and fall back to old behavior,\n      # use `relax_strict_optional_primitives` flag. more at\n      # https://github.com/nipunn1313/mypy-protobuf/tree/main#relax_strict_optional_primitives # pylint:disable=line-too-long\n      ['--mypy_out=relax_strict_optional_primitives:%s' % PYTHON_OUTPUT_PATH\n      ] +\n      # TODO(robertwb): Remove the prefix once it's the default.\n      ['--grpc_python_out=grpc_2_0:%s' % PYTHON_OUTPUT_PATH] + proto_files)\n\n  LOG.info('Regenerating Python proto definitions (%s).' % regenerate_reason)\n  ret_code = protoc.main(args)\n  if ret_code:\n    raise RuntimeError(\n        'Protoc returned non-zero status (see logs for details): '\n        '%s' % ret_code)\n\n  # copy resource files\n  for path in MODEL_RESOURCES:\n    shutil.copy2(os.path.join(PROJECT_ROOT, path), PYTHON_OUTPUT_PATH)\n\n  proto_packages = set()\n  # see: https://github.com/protocolbuffers/protobuf/issues/1491\n  # force relative import paths for proto files\n  compiled_import_re = re.compile('^from (.*) import (.*)$')\n  for file_path in find_by_ext(PYTHON_OUTPUT_PATH,\n                              ('_pb2.py', '_pb2_grpc.py', '_pb2.pyi')):\n    proto_packages.add(os.path.dirname(file_path))\n    lines = []\n    with open(file_path, encoding='utf-8') as f:\n      for line in f:\n        match_obj = compiled_import_re.match(line)","sourceCodeStart":478,"sourceCodeEnd":514,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/gen_protos.py#L478-L514","documentation":"After invoking protoc.main() with Beam's proto files (including grpc_python_out), gen_protos.py checks the return code. A non-zero status means protoc failed to compile the protos; the actual errors are in the logs, so this generic RuntimeError just reports the code.","triggerScenarios":"protoc exits non-zero during generate_proto_files due to malformed/unsupported proto files, an incompatible protoc version, or missing import paths.","commonSituations":"A too-old or too-new protoc/protobuf mismatch; corrupted or hand-edited .proto files; missing proto dependencies in the checkout.","solutions":["Rerun with logging enabled and read the protoc error lines printed before this exception.","Pin/use a protoc version matching the protobuf Python package expected by Beam.","Restore pristine .proto files from git (git checkout -- model/ sdks/python/proto) and retry."],"exampleFix":"// before\npython gen_protos.py 2>/dev/null\n// after\npython gen_protos.py 2>&1 | tee protoc.log  # inspect protoc errors above the RuntimeError","handlingStrategy":"try-catch","validationCode":"import subprocess\nv = subprocess.run(['protoc', '--version'], capture_output=True, text=True)\nassert v.returncode == 0 and 'libprotoc' in v.stdout, 'protoc missing or incompatible'","typeGuard":"def protoc_works():\n    import subprocess\n    r = subprocess.run(['protoc', '--version'], capture_output=True)\n    return r.returncode == 0","tryCatchPattern":"try:\n    generate_proto_files()\nexcept RuntimeError as e:\n    if 'Protoc returned non-zero status' in str(e):\n        # inspect protoc logs emitted earlier, fix proto sources or toolchain version, then retry","preventionTips":["Run generation with verbose logging and read protoc output before the exception.","Keep protoc and the protobuf Python package versions aligned.","Avoid hand-editing generated or source .proto files."],"tags":["protobuf","build","code-generation","toolchain"],"backgroundTag":"command-not-found","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"}