Tier Debug
Testing & Qualitytier-debugTier Debug is an Agent Skill for testing & quality published in the rustfs/rustfs repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/rustfs/rustfs/blob/HEAD/.agents/skills/tier-debug/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/tier-debug, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Tier / ILM Debugging
Full playbook: docs/operations/tier-ilm-debugging.md — read it before changing tier code.
Quick moves:
# 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; noversionIdmust 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-versionIDmetadata under bothx-rustfs-internal-*andx-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).