blender-errors-data
/blender-errors-data
Use when debugging Blender ReferenceError from removed objects, undo-invalidated bpy.data references, or stale ID pointers. Prevents the common crash of caching bpy.data references across undo/redo operations (references become invalid). Covers safe data access patterns, ID reference caching pitfalls, data lifecycle management, and bpy.data collections. Keywords: ReferenceError, undo, stale reference, bpy.data, ID pointer, data invalidation, removed object, data lifecycle, StructRNA, Blender crash, object disappeared after undo, StructRNA has been removed.
- Author
- sheepk95 ↗
- Repository
- The-Cartographer ↗
- Licence
- Apache-2.0
- Last repository change
- 29.10.2026
Assessment and security
- Files in this package
- 5
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 4
No signals detected. Repository changed on 29.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Use when debugging Blender ReferenceError from removed objects, undo-invalidated bpy.data references, or stale ID pointers. Prevents the common crash of caching bpy.data references across undo/redo operations (references become invalid). Covers safe data access patterns, ID reference caching pitfalls, data lifecycle management, and bpy.data collections. Keywords: ReferenceError, undo, stale reference, bpy.data, ID pointer, data invalidation, removed object, data lifecycle, StructRNA, Blender crash, object disappeared after undo, StructRNA has been removed.
Original author description
Use when debugging Blender ReferenceError from removed objects, undo-invalidated bpy.data references, or stale ID pointers. Prevents the common crash of caching bpy.data references across undo/redo operations (references become invalid). Covers safe data access patterns, ID reference caching pitfalls, data lifecycle management, and bpy.data collections. Keywords: ReferenceError, undo, stale reference, bpy.data, ID pointer, data invalidation, removed object, data lifecycle, StructRNA, Blender crash, object disappeared after undo, StructRNA has been removed.
How it works
- Quick Reference
- Error 1: ReferenceError from Removed Data
- Error 2: Undo Invalidates ALL References
- Error 3: Name Collision on Data Creation
- Error 4: Stale CollectionProperty References
- Error 5: File Operations Invalidate References
- Error 6: Blender 5.0 IDProperty Separation
- Mode Switching Invalidates Mesh Data
- Safe Data Access Patterns Summary
- Reference Links
SKILL.md preview
---
name: blender-errors-data
description: >
Use when debugging Blender ReferenceError from removed objects, undo-invalidated bpy.data
references, or stale ID pointers. Prevents the common crash of caching bpy.data references
across undo/redo operations (references become invalid). Covers safe data access patterns,
ID reference caching pitfalls, data lifecycle management, and bpy.data collections.
Keywords: ReferenceError, undo, stale reference, bpy.data, ID pointer, data invalidation, removed object, data lifecycle, StructRNA, Blender crash, object disappeared after undo, StructRNA has been removed.
license: MIT
compatibility: Designed for Claude Code. Requires Python 3.x.
metadata:
author: OpenAEC-Foundation
version: "1.0"
---
# blender-errors-data
## Quick Reference
### Critical Rules
**NEVER** store direct `bpy.data` references (objects, meshes, materials) across undo/redo, file load, or file revert operations — ALL Python pointers to Blender data are invalidated.
**NEVER** access a data block after calling `bpy.data.<collection>.remove()` on it — the StructRNA is freed and access raises `ReferenceError`.
**NEVER** assume `bpy.data.<collection>.new(name)` returns the exact name you passed — Blender appends `.001`, `.002`, etc. when a name already exists.
**NEVER** keep references to `CollectionProperty` items across `.add()` or `.remove()` calls — the underlying C array is re-allocated, invalidating all prior element pointers.
**NEVER** use `del obj["prop"]` to reset RNA-defined properties in Blender 5.0+ — use `obj.property_unset("prop")` instead.
**NEVER** use `obj["cycles"]` dict-like access for system properties in Blender 5.0+ — system properties are separated from custom properties.
**ALWAYS** store object/data block names (strings) or stable identifiers instead of direct `bpy` references when the reference must survive across operator execution, undo, or file operations.
**ALWAYS** re-fetch references from `bpy.data.<collection>` using `.get(name)` before accessing data that may have been invalidated.
**ALWAYS** store the return value of `bpy.data.<collection>.new()` directly in a variable — do not look up by name afterward.
**ALWAYS** use `bpy.data.objects.get(name)` (returns `None`) instead of `bpy.data.objects[name]` (raises `KeyError`) when the data block may not exist.
### Error Identification Table
| Error Message | Root Cause | Section |
|---------------|------------|---------|
| `ReferenceError: StructRNA of type X has been removed` | Accessing data block after `remove()` call | [Removed Data Access](#error-1-referenceerror-from-removed-data) |
| `ReferenceError` after Ctrl+Z | Undo invalidated all bpy references | [Undo Invalidation](#error-2-undo-invalidates-all-references) |
| `KeyError: 'bpy_prop_collection[key] not found'` | Name collision — Blender renamed the data block | [Name Collision](#error-3-name-collision-on-data-creation) |
| Crash / segfault after `CollectionProperty.add()` | Stale pointer to re-allocated array element | [Stale Collection References](#error-4-stale-collectionproperty-references) |
| `ReferenceError` after file load/revert | File operation rebuilt entire data model | [File Operation Invalidation](#error-5-file-operations-invalidate-references) |
| `KeyError` with `del obj["prop"]` in 5.0 | IDProperty separation — dict access removed for system props | [5.0 IDProperty Changes](#error-6-blender-50-idproperty-separation) |
### Decision Tree: Safe Data Access
```
Need to reference a Blender data block?
├── Will you use it immediately (same function, no operators called)?
│ └── YES → Direct reference is safe: obj = bpy.data.objects["Cube"]
├── Will an operator with undo run between store and access?
│ └── YES → Store NAME, re-fetch later: name = obj.name
├── Will undo/redo possibly occur (modal operator, interactive use)?
│ └── YES → Store NAME, re-fetch on every access
├── Will file load/revert occur?
│ └── YES → Store NAME, re-fetch after load_post handler fires
└── Will CollectionProperty.add()/remove() be called?
└── YES → Re-fetch ALL element references after modification
```
### Decision Tree: Diagnosing ReferenceError
```
Got ReferenceError: StructRNA of type X has been removed?
├── Did you call bpy.data.<collection>.remove() on this data?
│ └── YES → Do not access the variable after remove()
├── Did undo/redo happen since you obtained the reference?
│ └── YES → Re-fetch by name from bpy.data
├── Did a file load/revert happen?
│ └── YES → Re-fetch by name from bpy.data
├── Is this inside a modal operator?
│ └── YES → Store name in operator property, re-fetch each modal() call
└── Did you switch modes (Edit → Object)?
└── YES → Re-fetch mesh data references after mode switch
```
---
## Error 1: ReferenceError from Removed Data
When a data block is removed via `bpy.data.<collection>.remove()`, ANY Python variable still pointing to that data raises `ReferenceError` on access.
```python
# Blender 3.x/4.x/5.x: BROKEN
mesh = bpy.data.meshes.new("TempMesh")
bpy.data.meshes.remove(mesh)
print(mesh.name) # ReferenceError: StructRNA of type Mesh has been removed
# Blender 3.x/4.x/5.x: CORRECT
mesh = bpy.data.meshes.new("TempMesh")
mesh_name = mesh.name # Save name before removal if needed
bpy.data.meshes.remove(mesh)
mesh = None # Explicitly clear the reference
```
**Cascading removal**: Removing an object does NOT automatically remove its data. Removing a mesh does NOT automatically remove objects using it. Track dependencies manually.
```python
# Blender 3.x/4.x/5.x: Safe removal of object AND its data
obj = bpy.data.objects.get("MyObject")
if obj:
mesh = obj.data
bpy.data.objects.remove(obj)
if mesh and mesh.users == 0:
bpy.data.meshes.remove(mesh)
```
---
## Error 2: Undo Invalidates ALL References
When undo or redo occurs, Blender rebuilds the entire data model from its undo history. ALL Python references to `bpy.types.ID` subclasses (objects, meshes, materials, scenes, etc.) become invalid. This is the single most dangerous data access pitfall.
**When invalidation occurs:**
- `bpy.ops.ed.undo()` / `bpy.ops.ed.redo()`
- Interactive Ctrl+Z / Ctrl+Shift+Z by the user
- `bpy.ops.wm.open_mainfile()` (file load)
- `bpy.ops.wm.revert_mainfile()` (file revert)
- Any operator with built-in undo support that the user subsequently undoes
```python
# Blender 3.x/4.x/5.x: BROKEN: reference held across undo
obj = bpy.data.objects["Cube"]
bpy.ops.ed.undo()
obj.location.x = 1.0 # ReferenceError or crash
# Blender 3.x/4.x/5.x: CORRECT: store name, re-fetch
obj_name = bpy.data.objects["Cube"].name
bpy.ops.ed.undo()
obj = bpy.data.objects.get(obj_name)
if obj is not None:
obj.location.x = 1.0
```
See [references/examples.md](references/examples.md) for the `SafeObjectRef` wrapper pattern.
---
## Error 3: Name Collision on Data Creation
Blender enforces unique names within each `bpy.data` collection. When you create a data block with a name that already exists, Blender silently appends `.001`, `.002`, etc.
```python
# Blender 3.x/4.x/5.x: BROKEN: assuming exact name
bpy.data.meshes.new(name="MyMesh")
mesh = bpy.data.meshes["MyMesh"] # KeyError if "MyMesh" already existed — it became "MyMesh.001"
# Blender 3.x/4.x/5.x: CORRECT: capture return value
mesh = bpy.data.meshes.new(name="MyMesh") # Returns the actual data block
print(mesh.name) # May be "MyMesh.001" — use this variable, never look up by name
```
**Renaming also triggers this**: If you set `obj.name = "Cube"` but "Cube" already exists, Blender renames the OTHER object to "Cube.001". Code storing the old name of the other object will break.
---
## Error 4: Stale CollectionProperty References
`CollectionProperty` elements are stored in a contiguous C array. Calling `.add()` or `.remove()` may re-allocate the entire array, invalidating ALL Python references to existing elements.
```python
# Blender 3.x/4.x/5.x: BROKEN: stale pointer after re-allocation
items = bpy.context.scene.my_collection
first_item = items.add()
first_item.name = "First"
for i in range(100):
items.add() # May re-allocate entire array
first_item.name = "Updated" # CRASH or undefined behavior — pointer is invalid
# Blender 3.x/4.x/5.x: CORRECT: re-fetch by index after modifications
items = bpy.context.scene.my_collection
items.add()
items[len(items) - 1].name = "First"
for i in range(100):
items.add()
items[0].name = "Updated" # Safe — accessed by index, not stale pointer
```
---
## Error 5: File Operations Invalidate References
File load and revert rebuild the entire data model, identical to undo invalidation. References obtained before the file operation are invalid.
```python
# Blender 3.x/4.x/5.x: BROKEN
obj = bpy.data.objects["Wall"]
bpy.ops.wm.open_mainfile(filepath="/path/to/other.blend")
print(obj.name) # ReferenceError — entire data model was replaced
# Blender 3.x/4.x/5.x: CORRECT: use load_post handler
from bpy.app.handlers import persistent
@persistent
def on_file_loaded(filepath):
obj = bpy.data.objects.get("Wall")
if obj:
print(f"Found Wall in new file: {obj.name}")
bpy.app.handlers.load_post.append(on_file_loaded)
```
---
## Error 6: Blender 5.0 IDProperty Separation
Blender 5.0 separates system-defined properties (RNA properties defined via `bpy.props`) from user-defined custom properties. Dict-like access to system properties is removed.
```python
# Blender 4.x: Works (but deprecated)
value = bpy.context.scene["cycles"] # Accesses Cycles settings via dict syntax
del obj["my_rna_prop"] # Resets RNA property via dict deletion
# Blender 5.0+: BROKEN
value = bpy.context.scene["cycles"] # KeyError — system props not in dict
del obj["my_rna_prop"] # Fails for RNA-defined properties
# Blender 5.0+: CORRECT
value = bpy.context.scene.cycles # Access via attribute
obj.property_unset("my_rna_prop") # Reset RNA property to default
# Custom properties still use dict access in ALL versions
obj["my_custom_prop"] = 42 # Works in 3.x/4.x/5.x
value = obj["my_custom_prop"] # Works in 3.x/4.x/5.x
del obj["my_custom_prop"] # Works in 3.x/4.x/5.x
```
**Migration for legacy files**: Blender 5.0 auto-duplicates old IDProperties into system storage when opening pre-5.0 files. Clean up with:
```python
# Blender 5.0+: Cleanup duplicated IDProperties from legacy files
for ob in bpy.data.objects:
sys_props = ob.bl_system_properties_get()
# Migrate values if needed, then remove old custom prop duplicates
```
---
## Mode Switching Invalidates Mesh Data
Switching between Edit Mode and Object Mode re-allocates mesh data arrays. References to `mesh.vertices`, `mesh.polygons`, `mesh.edges`, and UV layers obtained before the switch are invalid.
```python
# Blender 3.x/4.x/5.x: BROKEN
verts = bpy.context.active_object.data.vertices
bpy.ops.object.mode_set(mode='EDIT')
bpy.ops.object.mode_set(mode='OBJECT')
print(verts[0].co) # Crash or stale data — verts pointer is invalid
# Blender 3.x/4.x/5.x: CORRECT: re-fetch after mode switch
bpy.ops.object.mode_set(mode='EDIT')
bpy.ops.object.mode_set(mode='OBJECT')
verts = bpy.context.active_object.data.vertices # Re-fetch
print(verts[0].co) # Safe
```
---
## Safe Data Access Patterns Summary
| Pattern | When to Use | Implementation |
|---------|-------------|----------------|
| Store name, re-fetch | Modal operators, handlers, any long-lived reference | `name = obj.name` → `bpy.data.objects.get(name)` |
| Use `.get()` not `[]` | Any lookup where data may not exist | `bpy.data.objects.get("X")` returns `None` |
| Capture return value | After `.new()` calls | `mesh = bpy.data.meshes.new("X")` |
| Re-fetch after collection mutation | After `.add()` / `.remove()` on CollectionProperty | Access by index, not stored reference |
| Null-check after re-fetch | After undo, file load, or any invalidation point | `if obj is not None:` |
| Use `@persistent` on handlers | Any handler in an addon | Without it, handler is removed on file load |
---
## Reference Links
- [references/methods.md](references/methods.md) — Data access API signatures for bpy.data collections, ID lifecycle, and property access
- [references/examples.md](references/examples.md) — Complete error resolution examples with safe patterns
- [references/anti-patterns.md](references/anti-patterns.md) — Common data access mistakes with explanations
### Official Sources
- https://docs.blender.org/api/current/info_gotcha.html
- https://docs.blender.org/api/current/info_gotchas_internal_data_and_python_objects.html
- https://docs.blender.org/api/current/info_gotchas_crashes.html
- https://developer.blender.org/docs/release_notes/5.0/python_api/
Files in this package (5)
- LICENSE 1 KB
- SKILL.md 13 KB
- references/anti-patterns.md 10 KB
- references/examples.md 10 KB
- references/methods.md 8 KB
Versions
The database has no other skills named blender-errors-data.
Database snapshot: 13.11.2026 · package version efd52df1a395 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100blender-core-runtime
Use when dealing with Blender Python runtime behavior -- mathutils, threading, handlers, timers, or crashes after undo/redo. Prevents the #1 runtime crash: using threading for bpy operations instead of bpy.app.timers, or caching bpy.data references across undo boundaries. Covers… - 100blender-core-api
Use when writing Blender Python scripts that access bpy module structure, RNA data, the context system, dependency graph, or operator invocation. Prevents the common mistake of accessing context attributes outside their valid scope or calling operators without checking poll().… - 90blender-python-automation
Use when the task is to automate Blender through bpy with bounded, reviewable scripts. - 100blender-addon-development
Write Blender 5.2 add-ons as extensions - blender_manifest.toml, operators/panels/menus/property groups/preferences, bpy.props rules after 5.0, undo/redo, modal and timer patterns, gpu drawing (no bgl), bundling Python wheels, CLI validate/build/install, testing headless,… - 100blender
Use when scripting Blender's bpy API or batch-processing scenes headless — bpy.data mesh/object creation, Geometry Nodes groups via interface.new_socket, glTF/OBJ/STL export (export_scene.gltf, wm.obj_export, wm.stl_export), GIS footprints to building massing, add-on/extension… - 100blender-addon-development
Guides Blender addon development - operators, UI panels, bpy.props, poll() methods and registration. Use when creating a Blender addon, building an operator or UI panel, or writing Blender Python for a tool.