What a Robot Policy Checkpoint Contains, and Why It Won't Move

A checkpoint is not a model. It is a directory that happens to contain a model, plus three other things that are just as load bearing: the numbers used to scale your robot's joint angles into the range the network was trained on, a config that describes the architecture the weights belong to, and a pile of training state that only matters if you plan to resume. Get any of the four wrong and the arm still moves. It just moves to the wrong place.

This page opens real checkpoints and reads out what is in them. Every file name, byte count and tensor key below was pulled from a public repository and re-checked against it in August 2026, not recalled from memory. The three examples are a SmolVLA base checkpoint, an ACT checkpoint from the LeRobot model zoo, and NVIDIA's GR00T N1.7 base. Then we go through why copying one of these from the machine that trained it to the machine that runs the arm fails more often than it works.

The four parts of a checkpoint

Whatever framework wrote it, a policy checkpoint decomposes into the same four categories. Knowing which category a file belongs to tells you whether you can delete it, whether it has to travel with the weights, and what breaks if it is stale.

Case 1: a LeRobot checkpoint on disk

LeRobot writes one directory per saved training step, zero padded to at least six digits, under checkpoints/ in the run output directory, plus a last symlink pointing at the newest one. The layout is documented in the docstring of save_checkpoint. It changed between releases, so the version matters.

005000/                              # training step at checkpoint
|-- pretrained_model/
|   |-- config.json                   # policy config
|   |-- model.safetensors             # policy weights
|   |-- train_config.json             # train config
|   |-- processor.json                # processor config (if a preprocessor was passed)
|   `-- step_*.safetensors            # processor state files (if any)
`-- training_state/
    |-- optimizer_param_groups.json
    |-- optimizer_state.safetensors
    |-- rng_state.safetensors
    |-- scheduler_state.json
    `-- training_step.json

005000/
|-- pretrained_model/
|   |-- config.json
|   |-- model.safetensors             # or pytorch_model_fsdp_0/ for DCP formats
|   |-- train_config.json
|   |-- policy_preprocessor.json
|   |-- policy_preprocessor_step_*.safetensors
|   |-- policy_postprocessor.json
|   `-- policy_postprocessor_step_*.safetensors
`-- training_state/
    |-- optimizer_param_groups.json
    |-- optimizer_state.safetensors   # or optimizer_0/ for sharded runs
    |-- rng_state.safetensors
    |-- scheduler_state.json
    `-- training_step.json            # step + dp_world_size, batch_size, grad_accum, topology

Three things moved between the release you install and the branch it will become, and one thing that looks like it moved did not. The module changed path in v0.6.0, which is enough to break any script that imported it by path. training_step.json grew from a bare step counter into a snapshot of the run topology, so a resume can complain when the parallelism or the gradient-accumulation cadence changed. And main added artifacts for sharded runs that no release writes yet.

The last row is the one worth dwelling on, because it looks like a breaking rename and is not one. PolicyProcessorPipeline has built state file names out of the pipeline name, the step index and the registry name since v0.5.1, and v0.5.1's save_checkpoint already accepted both a preprocessor and a postprocessor. Only the docstring changed, from generic placeholders to the concrete names the released code was writing all along. That is why lerobot/smolvla_base on the Hub carries a file called policy_preprocessor_step_5_normalizer_processor.safetensors even though no tagged release names that file anywhere.

What the real repositories contain

These are byte counts from the Hugging Face API, not estimates. They show how lopsided a checkpoint is: the part that is easiest to lose is also the smallest.

Note what lerobot/pi05_base does not have: it ships policy_preprocessor.json and policy_postprocessor.json but no normalizer state file. The base Pi0.5 checkpoint carries the pipeline structure without the statistics, because the statistics only exist once you have picked a dataset. lerobot/act_aloha_sim_transfer_cube_human has no processor files at all, because it predates them.

What is actually inside model.safetensors

safetensors is deliberately boring, which is the point. The file is eight bytes holding an unsigned little-endian 64-bit integer N, then N bytes of UTF-8 JSON, then the raw tensor bytes. The JSON header maps each tensor name to its dtype, its shape and a pair of byte offsets into the data region. There is one reserved key, __metadata__, and it may only hold a flat string-to-string map. No pickle, no code execution, no surprises when you open a file someone sent you.

That means you can read the entire structure of a 14 GB weight file by fetching its first few hundred kilobytes. Here is the whole reader, and the output from the ACT checkpoint above.

import json, struct, sys

with open(sys.argv[1], "rb") as f:
    n = struct.unpack("<Q", f.read(8))[0]     # header length
    header = json.loads(f.read(n))            # {name: {dtype, shape, data_offsets}}

meta = header.pop("__metadata__", None)
print(f"header bytes: {n}   tensors: {len(header)}   metadata: {meta}")
for name, spec in header.items():
    print(f"{name:60s} {spec['dtype']:5s} {spec['shape']}")

normalize_inputs.buffer_observation_images_top.mean   F32 [3, 1, 1]
normalize_inputs.buffer_observation_images_top.std    F32 [3, 1, 1]
normalize_inputs.buffer_observation_state.mean        F32 [14]
normalize_inputs.buffer_observation_state.std         F32 [14]
normalize_targets.buffer_action.mean                  F32 [14]
normalize_targets.buffer_action.std                   F32 [14]
unnormalize_outputs.buffer_action.mean                F32 [14]
unnormalize_outputs.buffer_action.std                 F32 [14]

The [14] is a bimanual ALOHA setup: seven values per side. An SO-100 records six, five joints plus the gripper, which is exactly the shape lerobot/smolvla_base declares for observation.state and action. Those two shapes will never load into each other, which is the good case. The dangerous case is two checkpoints that agree on shape and disagree on what the numbers mean.

The 640 bytes that decide whether the arm works

Here is the entire normaliser state of lerobot/smolvla_base, decoded. Six tensors, 144 bytes of payload, 488 bytes of JSON header, 640 bytes on disk. It sits next to a 907 MB weight file.

so100-blue.buffer.action.mean   [   1.4212, 125.7205, 125.4193,  63.7832, -106.5401,   3.3485]
so100-blue.buffer.action.std    [  14.0820,  39.4314,  18.2381,  23.4898,   38.1112,   5.0483]
so100-red.buffer.action.mean    [   2.4387, 124.9379, 123.5578,  66.9926, -103.8768,   2.8912]
so100-red.buffer.action.std     [  14.2992,  42.7722,  18.8763,  21.6519,   33.5341,   4.4780]
so100.buffer.action.mean        [   1.5959, 119.9442, 109.7698,  56.7055,  -27.4227,  12.0028]
so100.buffer.action.std         [  26.3918,  52.4114,  49.8538,  36.9983,   59.3600,  19.0400]

Look at the fifth column, the wrist. The so100-blue statistics put its mean at -106.54; the plain so100 statistics put it at -27.42. Mean-and-standard-deviation normalisation means the model emits a normalised value and the postprocessor computes value times std plus mean, so a predicted normalised zero comes out at -106.54 under one set of statistics and at -27.42 under the other. The gap is 79.1 raw units: 2.1 standard deviations under the so100-blue statistics, 1.3 under the plain so100 ones. Whatever unit that arm recorded in, moving a wrist joint by more than a standard deviation is the difference between closing on an object and swiping past it, and it comes out of a 640 byte file with no error message anywhere in the stack.

This is why the LeRobot dataset and the checkpoint are a matched pair, not two independent artifacts. The statistics are computed over the episodes you recorded. Re-record with a different calibration zero point and the same policy weights now expect a coordinate frame your arm no longer produces. If your policy moves confidently to a consistently wrong offset, this is the first thing to check, ahead of anything about the model, and it is the pattern behind a policy that only works in one setup.

Case 2: a GR00T checkpoint is a different animal

NVIDIA's Isaac-GR00T stack builds on the Hugging Face Transformers trainer, so a GR00T checkpoint looks like a language-model checkpoint with robot-specific extras bolted on. Here is the shipped nvidia/GR00T-N1.7-3B repository.

Three structural differences from LeRobot matter. First, GR00T addresses its statistics by embodiment tag, so one checkpoint carries normalisation for many robots at once, and the loader raises a hard ValueError listing the supported tags if you ask for one that is not there. That is a better failure than a warning. Second, it normalises with percentiles: use_percentiles is true and use_mean_std is false in the shipped processor config, so the state and action ranges come from q01 and q99, not from mean and standard deviation. Third, the shipped nvidia/GR00T-N1.7-3B processor config lists only eight embodiment tags, none of them an SO-100 class arm, which is why the base model cannot be driven directly on your arm and has to be fine-tuned first.

Why moving a checkpoint between machines usually fails

Every one of these has a specific cause and a specific fix. None of them is the model being bad. The order below is roughly how often we see them, and most of them have a dedicated page under the failure modes index.

There is one more that is not a bug but catches people anyway. Isaac-GR00T's FinetuneConfig, the dataclass its fine-tune CLI is generated from, defaults to save_total_limit 5 and save_steps 1000, so older checkpoints are deleted as new ones are written. If you were planning to compare step 2000 against step 20000 later, you have to raise the limit before the run, not after. The same applies to the GR00T N1.7 on SO-100 guide, where saveSteps is the one extra knob the form exposes.

Checking a checkpoint before you trust it

Five minutes of inspection beats an afternoon of watching an arm miss a cube. This runs against any LeRobot-style checkpoint directory, whether it came off your own GPU, out of a dataset-driven run, or off the Hub.

1. 1
   List the directory and classify every file

   You are looking for four things: a weight file, a config, something holding statistics, and optionally a training_state directory. If the statistics are missing, stop here. The awk pass keeps this portable; find's -printf is GNU only and fails on a Mac.

   bash

   find outputs/train/my_run/checkpoints/last/ -maxdepth 2 -type f -exec ls -l {} + \
     | awk '{printf "%12s  %s\n", $5, $NF}' | sort -k2

2. 2
   Read the safetensors header without loading the weights

   Confirms the tensor count, catches an old-style checkpoint whose normalisation buffers are still inside the state dict, and tells you the dtype.

   bash

   python - <<'EOF'
   import json, struct
   f = open("pretrained_model/model.safetensors", "rb")
   n = struct.unpack("<Q", f.read(8))[0]
   h = json.loads(f.read(n))
   h.pop("__metadata__", None)
   print("tensors:", len(h))
   print("norm buffers:", [k for k in h if "normal" in k])
   print("dtypes:", sorted({v["dtype"] for v in h.values()}))
   EOF

3. 3
   Check the shapes in config.json against your robot

   input_features and output_features declare exactly what the policy expects. An SO-100 class arm records six values, five joints plus the gripper, so observation.state and action both carry shape [6]; that is what lerobot/smolvla_base declares. Camera keys have to match the names your client publishes, not just the count.

   bash

   python -c "import json,sys; c=json.load(open('pretrained_model/config.json')); print(c['type'], c.get('device')); print(json.dumps({'in':c['input_features'],'out':c['output_features']}, indent=1))"

4. 4
   Print the normalisation statistics and sanity check the ranges

   The means should look like joint angles your arm actually reaches. A mean of 0.0 with a std of 1.0 across the board means the statistics were never filled in.

   bash

   python - <<'EOF'
   import glob, json, struct
   for path in glob.glob("pretrained_model/*normalizer*.safetensors"):
       b = open(path, "rb").read()
       n = struct.unpack("<Q", b[:8])[0]
       h, data = json.loads(b[8:8+n]), b[8+n:]
       print(path)
       for k, v in h.items():
           s, e = v["data_offsets"]
           vals = struct.unpack("<%df" % ((e-s)//4), data[s:e])
           print(" ", k, [round(x, 3) for x in vals])
   EOF

5. 5
   Load it once with strict=True on a throwaway box

   This is the only cheap way to turn LeRobot's silent warnings into an exception you cannot miss. Do it before the checkpoint goes anywhere near a powered arm.

   python

   from lerobot.policies.factory import get_policy_class
   
   cls = get_policy_class("act")           # or smolvla, pi05
   policy = cls.from_pretrained("pretrained_model", strict=True)
   print(sum(p.numel() for p in policy.parameters()), "parameters loaded")

6. 6
   Strip the training state before you copy it to the robot

   The pretrained_model subtree is everything inference needs. Leaving optimizer state behind saves bandwidth and removes the pickled files from the machine that talks to the servos.

   bash

   rsync -av --exclude 'training_state/' --exclude '*.bin' --exclude '*.pt' \
     outputs/train/my_run/checkpoints/last/ pi@robot.local:/opt/policy/

Two ways to get a checkpoint you can trust

git clone https://github.com/huggingface/lerobot.git
cd lerobot && git checkout v0.6.1
pip install -e ".[smolvla]"

lerobot-train \
  --policy.type=smolvla \
  --dataset.repo_id=<your-hf-user>/<your-dataset> \
  --batch_size=2 \
  --steps=20000 \
  --output_dir=outputs/train/smolvla_so100 \
  --job_name=smolvla_so100

lerobot-train \
  --config_path=outputs/train/smolvla_so100/checkpoints/last/pretrained_model/train_config.json \
  --resume=true

Where none of this helps

Three honest limits, because a checkpoint you understand perfectly can still fail for reasons that have nothing to do with its contents.

• A correct checkpoint served from far away is still a bad policy. Per-action-step time on this platform runs from 20 ms for ACT to 485 ms for Pi0.5, and adding public-internet round trips on top turns a working policy into a hesitant one. Remote inference is fine for slow pick and place and wrong for fast reactive motion. See inference latency for what that budget is actually spent on.
• Nothing in a checkpoint tells you whether the data behind it was any good. Statistics computed over episodes with a frozen camera or a servo at its limit look completely normal. That is a dataset problem and it needs a data collection fix, not a checkpoint fix.
• Reproducing a GR00T run bit for bit is not possible from the checkpoint. Its fine-tune CLI is generated by tyro from a FinetuneConfig dataclass that has no seed field at all, so two runs on the same data will not match. lerobot has one, defaulting to 1000. If you need reproducibility, that constrains which model you can use.

The flip side is that a checkpoint you can read is a checkpoint you can debug. Most of the reports that start with the policy being broken end with a config field or a statistics file, and both are legible in under a minute once you know where to look. If you are still stuck after the checks above, a falling loss with a policy that does nothing and a policy that freezes mid motion cover the two failure shapes that are not checkpoint problems.

Frequently asked questions

Closing

A checkpoint is four artifacts pretending to be one. The weights are the part everyone talks about and the part least likely to be your problem. The statistics are 640 bytes that decide where the arm goes. The config records the machine that wrote it, down to the GPU vendor. The training state is the largest thing in the directory and does nothing at inference time. Learn to read all four with the header dump above and the class of failures that starts with the model being broken mostly evaporates.

If you want to compare what the different families do before you commit to producing checkpoints in one of their formats, the five trainable policies are laid out with parameter counts and latency, GR00T N1.7 against Pi0.5 goes head to head, and the VLA overview covers why these architectures are shaped the way they are. For the hardware side, the SO-100 guide starts from an unopened parts box, the training docs describe the run itself, and the public dataset directory has recordings you can point a trainer at today.