# Tier Debug

> Debug ILM tiering / lifecycle transition issues — NoSuchVersion on tier GET, restore failures, xl.meta inspection, remote-tier versionId tracing. Use when investigating tiered/transitioned objects, warm backends, or transition metadata.

- Skill: `rustfs/tier-debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rustfs/tier-debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rustfs/tier-debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: rustfs (https://skillmd.com/u/rustfs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rustfs/tier-debug

---


# Tier / ILM Debugging

Playbook: [docs/operations/tier-ilm-debugging.md](../../../docs/operations/tier-ilm-debugging.md).
Read the section matching the symptom: metadata/`xl.meta`, runtime versionId,
manual jobs, or retained-record recovery. Read the local-first expiry invariant
before changing cleanup ordering. Before a reconcile/disposition action, read
its entire procedure and retain its exact-evidence and confirmation gates.

Quick moves:

```bash
# Inspect transition metadata on disk (one xl.meta per erasure shard disk)
cargo run -p rustfs-filemeta --example dump_fileinfo -- "/path/to/{bucket}/{object}/xl.meta"

# Trace what versionId is sent to the remote tier
RUST_LOG=rustfs_ecstore::bucket::lifecycle=debug ./target/debug/rustfs …
```

Interpretation:

- `transition_ver_id: <none>` → correct for an unversioned tier bucket; no
  `versionId` must be sent on tier GET/DELETE.
- `transition_ver_id: 00000000-…` (nil) → corrupt legacy write-back; readers
  must filter it out, never send it.
- Empty-string `transitioned-versionID` metadata under both
  `x-rustfs-internal-*` and `x-minio-internal-*` keys → object went to an
  unversioned tier bucket.

Code entry points: `crates/ecstore/src/bucket/lifecycle/bucket_lifecycle_ops.rs`
(ILM actions), `crates/ecstore/src/services/tier/` (warm backends),
`crates/filemeta/src/filemeta/version.rs` (metadata read/write + regression
tests).