{"id":22157433,"url":"https://github.com/decryptu/minecraft-nbt-depth-checker","last_synced_at":"2025-10-12T16:30:59.822Z","repository":{"id":265961545,"uuid":"896978080","full_name":"Decryptu/minecraft-nbt-depth-checker","owner":"Decryptu","description":"A Python utility to diagnose NBT depth issues in Minecraft save files and prevent 'tried to read NBT tag that was too big' crashes","archived":false,"fork":false,"pushed_at":"2024-12-01T20:20:35.000Z","size":584,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-22T21:38:47.136Z","etag":null,"topics":["forge","java","minecraft","minecraft-forge","nbt","nbt-parser","python","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Decryptu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-01T19:06:50.000Z","updated_at":"2025-01-16T02:49:20.000Z","dependencies_parsed_at":"2024-12-02T02:16:44.170Z","dependency_job_id":null,"html_url":"https://github.com/Decryptu/minecraft-nbt-depth-checker","commit_stats":null,"previous_names":["decryptu/minecraft-nbt-depth-checker"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Decryptu%2Fminecraft-nbt-depth-checker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Decryptu%2Fminecraft-nbt-depth-checker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Decryptu%2Fminecraft-nbt-depth-checker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Decryptu%2Fminecraft-nbt-depth-checker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Decryptu","download_url":"https://codeload.github.com/Decryptu/minecraft-nbt-depth-checker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236246985,"owners_count":19118476,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["forge","java","minecraft","minecraft-forge","nbt","nbt-parser","python","python3"],"created_at":"2024-12-02T03:08:50.326Z","updated_at":"2025-10-12T16:30:54.457Z","avatar_url":"https://github.com/Decryptu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Minecraft NBT Depth Checker\n\nA Python utility to analyze, diagnose, and fix NBT depth issues in Minecraft save files, particularly useful when encountering the \"tried to read nbt tag that was too big tried to allocate\" error caused by excessive NBT tag depths.\n\n![Minecraft NBT Error](img/error.png)\n\n## Overview\n\nWhen Minecraft worlds become complex or corrupted, they can develop issues with NBT (Named Binary Tag) structures becoming too deep or complex. This commonly manifests as a `java.lang.RuntimeException` with a message about trying to allocate too many bytes when attempting to load the world.\n\nThis tool helps you identify which parts of your save file's `level.dat` are reaching concerning depths, and offers the option to automatically reduce the complexity of problematic structures while maintaining data integrity.\n\n## Example Output\n\nHere's what the tool's output looks like when analyzing a problematic level.dat file:\n\n```\n=================================================\n                NBT Depth Analyzer               \n=================================================\n\n=================================================\n               Analysis Results                   \n=================================================\n\nFile: level.dat\nTotal tags: 1,432\nMaximum depth: 11\nPath to maximum depth: Data \u003e ... \u003e parameters \u003e continentalness\n\n=================================================\n              Deepest Structures                 \n=================================================\n\nDepth 11:\n  → Data \u003e WorldGenSettings \u003e ... \u003e parameters \u003e continentalness\n  → Data \u003e WorldGenSettings \u003e ... \u003e parameters \u003e continentalness\n\n⚠️  WARNING: Found 2 structure(s) exceeding recommended depth of 100\nWould you like to attempt to reduce these deep structures? (yes/no):\n```\n\nWith full paths enabled (--full-paths):\n\n```\nPath to maximum depth: Data \u003e WorldGenSettings \u003e dimensions \u003e minecraft:overworld \u003e generator \u003e biome_source \u003e original_biome_source \u003e biomes \u003e [0] \u003e parameters \u003e continentalness\n```\n\n## Features\n\n- Analyzes Minecraft level.dat files for NBT tag depths\n- Reports maximum depth found and the full path to the deepest tags\n- Identifies all deep structures with their complete paths\n- Highlights potentially problematic deep structures\n- Cross-platform color-coded output support\n- Configurable display options:\n  - Full path display (--full-paths/-f)\n  - Custom warning depth threshold (--warning-depth/-w)\n- Offers automatic structure reduction with safety features:\n  - Creates automatic backups before any modifications\n  - Reduces complex structures while maintaining NBT integrity\n  - Provides clear paths to backups for easy restoration\n- Helps diagnose and fix \"tried to allocate\" errors related to NBT complexity\n\n## Requirements\n\n- Python 3.6 or higher\n- NBT library (`NBT`)\n\n## Installation\n\n1. Clone this repository:\n\n```bash\ngit clone https://github.com/decryptu/minecraft-nbt-depth-checker\ncd minecraft-nbt-depth-checker\n```\n\n2. Install the required dependency:\n\n```bash\npip install -r requirements.txt\n```\n\n## Usage\n\nBasic usage:\n\n```bash\npython nbt_depth_checker.py path/to/your/level.dat\n```\n\nWith full paths displayed:\n\n```bash\npython nbt_depth_checker.py --full-paths path/to/your/level.dat\n# or\npython nbt_depth_checker.py -f path/to/your/level.dat\n```\n\nWith custom warning depth:\n\n```bash\npython nbt_depth_checker.py --warning-depth 50 path/to/your/level.dat\n# or\npython nbt_depth_checker.py -w 50 path/to/your/level.dat\n```\n\nCombine options:\n\n```bash\npython nbt_depth_checker.py -f -w 50 path/to/your/level.dat\n```\n\nShow help:\n\n```bash\npython nbt_depth_checker.py --help\n```\n\nThe level.dat file is typically found in your world save folder:\n\n- Windows: `%appdata%/.minecraft/saves/[world_name]/level.dat`\n- Linux: `~/.minecraft/saves/[world_name]/level.dat`\n- macOS: `~/Library/Application Support/minecraft/saves/[world_name]/level.dat`\n\nThe script will:\n\n1. Analyze the NBT structure\n2. Show the maximum depth and paths to deep structures\n3. If issues are found, offer to automatically reduce structure complexity\n4. Create a backup before making any changes\n5. Attempt to safely reduce deep structures\n6. Provide backup restoration information if needed\n\n## Display Options\n\n- `--full-paths` or `-f`: Shows complete paths instead of truncated versions\n- `--warning-depth` or `-w`: Sets custom depth threshold for warnings (default: 100)\n\n## Safety Features\n\nWhen reducing NBT structures, the tool:\n\n1. Always creates a timestamped backup first\n2. Reduces structures incrementally\n3. Maintains NBT tag types and integrity\n4. Provides clear backup paths for restoration\n5. Reports any structures it couldn't safely reduce\n\n## Common Issues\n\nThe \"tried to allocate\" error typically occurs in the level.dat file of your Minecraft save. This can happen due to:\n\n- Complex redstone contraptions\n- Large numbers of entities in a small area\n- Corrupted chunks\n- Mod-related issues\n- World conversion issues\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments\n\n- Thanks to [minecraft-nbt-lib](https://github.com/twoolie/NBT) for providing the NBT file parsing functionality\n- Inspired by Minecraft save debugging challenges and community needs\n\n## Technical Background\n\nMinecraft uses NBT (Named Binary Tag) format to store various game data in the level.dat file. While the format allows for nested structures, excessive nesting can lead to memory allocation issues. This tool helps identify and safely reduce such complex structures while maintaining data integrity.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecryptu%2Fminecraft-nbt-depth-checker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdecryptu%2Fminecraft-nbt-depth-checker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecryptu%2Fminecraft-nbt-depth-checker/lists"}