{"record":{"id":"31462158ac120c6a","repo":"jax-ml/jax","slug":"invalid-trace-folder-latest-trace-folder","errorCode":null,"errorMessage":"Invalid trace folder: {latest_trace_folder}","messagePattern":"Invalid trace folder: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"warning","filePath":"jax/_src/profiler.py","lineNumber":221,"sourceCode":"        set_metadata(f\"{backend.platform}_version\", backend.platform_version)\n      except RuntimeError:\n        pass\n    _profile_state.profile_session = _profiler.ProfilerSession(options)\n    _profile_state.create_perfetto_link = create_perfetto_link\n    _profile_state.create_perfetto_trace = (\n        create_perfetto_trace or create_perfetto_link)\n    _profile_state.log_dir = str(log_dir)\n\n\ndef _write_perfetto_trace_file(log_dir: os.PathLike | str):\n  # Navigate to folder with the latest trace dump to find `trace.json.jz`\n  trace_folders = (pathlib.Path(log_dir).absolute() / \"plugins\" / \"profile\").iterdir()\n  latest_trace_folder = max(trace_folders, key=os.path.getmtime)\n  trace_jsons = latest_trace_folder.glob(\"*.trace.json.gz\")\n  try:\n    trace_json, = trace_jsons\n  except ValueError as value_error:\n    raise ValueError(f\"Invalid trace folder: {latest_trace_folder}\") from value_error\n\n  logger.info(\"Loading trace.json.gz and removing its metadata...\")\n  # Perfetto doesn't like the `metadata` field in `trace.json` so we remove\n  # it.\n  # TODO(sharadmv): speed this up by updating the generated `trace.json`\n  # to not include metadata if possible.\n  with gzip.open(trace_json, \"rb\") as fp:\n    trace = json.load(fp)\n    del trace[\"metadata\"]\n  perfetto_trace = latest_trace_folder / \"perfetto_trace.json.gz\"\n  logger.info(\"Writing perfetto_trace.json.gz...\")\n  with gzip.open(perfetto_trace, \"w\") as fp:\n    fp.write(json.dumps(trace).encode(\"utf-8\"))\n  return perfetto_trace\n\nclass _PerfettoServer(http.server.SimpleHTTPRequestHandler):\n  \"\"\"Handles requests from `ui.perfetto.dev` for the `trace.json`\"\"\"\n","sourceCodeStart":203,"sourceCodeEnd":239,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/profiler.py#L203-L239","documentation":"When creating a Perfetto trace file, JAX globs `*.trace.json.gz` in the newest profile folder under log_dir/plugins/profile. If that folder doesn't contain exactly one such file, the tuple-unpack fails and is re-raised as 'Invalid trace folder'.","triggerScenarios":"Calling stop_trace with `create_perfetto_trace=True` when the latest profile folder has zero or multiple trace.json.gz files — e.g. a partially written export, a crashed session, or a stale/corrupt folder.","commonSituations":"Interrupted profiling runs; multiple profile outputs colliding in one folder; permissions or disk-full issues preventing the trace.json.gz write; log_dir pointed at a directory with hand-created folders.","solutions":["Inspect the newest folder under <log_dir>/plugins/profile and remove corrupt/duplicate artifacts, then re-profile","Re-run the full start_trace/stop_trace cycle cleanly","Disable create_perfetto_trace if you only need the raw profile files"],"exampleFix":"# before\njax.profiler.start_trace('/tmp/log', create_perfetto_trace=True)\n... \njax.profiler.stop_trace()  # folder has no trace.json.gz\n# after\njax.profiler.start_trace('/tmp/log')\njax.profiler.stop_trace()","handlingStrategy":"validation","validationCode":"import pathlib, os\nlog_dir = pathlib.Path('/tmp/log')\nfolders = (log_dir/'plugins'/'profile').iterdir()\nlatest = max(folders, key=os.path.getmtime)\ntraces = list(latest.glob('*.trace.json.gz'))\nassert len(traces) == 1, f'expected 1 trace file, found {len(traces)}'","typeGuard":null,"tryCatchPattern":"try:\n    jax.profiler.stop_trace()\nexcept ValueError as e:\n    if 'Invalid trace folder' in str(e):\n        # raw profile still exists; skip perfetto generation\n        pass\n    else:\n        raise","preventionTips":["Use a fresh log_dir per profiling run","Don't interrupt trace export; check disk space"],"tags":["jax","profiler","perfetto","filesystem"],"backgroundTag":"corrupt-output-artifact","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}