Diagnose and resolve Python API errors caused by Blender version differences. This skill activates when encountering AttributeError, ImportError, TypeError, KeyError, or RuntimeError in Blender scripts that result from using removed, renamed, or restructured APIs.
Dependency: blender-core-versions — version matrix and detection API.
1. Error Diagnosis Decision Tree
When a Blender Python script raises an error, follow this decision tree:
ERROR RECEIVED
│
├── AttributeError?
│ ├── "has no attribute 'bevel_weight'" → Blender 4.0+ mesh attribute migration [E-01]
│ ├── "has no attribute 'crease'" → Blender 4.0+ mesh attribute migration [E-01]
│ ├── "has no attribute 'use_auto_smooth'" → Blender 4.1+ auto-smooth removal [E-02]
│ ├── "has no attribute 'auto_smooth_angle'" → Blender 4.1+ auto-smooth removal [E-02]
│ ├── "has no attribute 'face_maps'" → Blender 4.0+ face maps removal [E-03]
│ ├── "has no attribute 'layers'" (on Bone) → Blender 4.0+ bone collections [E-04]
│ ├── "has no attribute 'bone_groups'" → Blender 4.0+ bone collections [E-04]
│ ├── "has no attribute 'inputs'" (on NodeTree) → Blender 4.0+ interface API [E-05]
│ ├── "has no attribute 'outputs'" (on NodeTree) → Blender 4.0+ interface API [E-05]
│ ├── "has no attribute 'sculpt_tool'" → Blender 5.0+ brush rename [E-06]
│ ├── "has no attribute 'node_tree'" (on Scene) → Blender 5.0+ compositor [E-07]
│ ├── "has no attribute 'use_nodes'" (on Scene) → Blender 5.0+ compositor [E-07]
│ ├── "has no attribute 'end_frame'" (on Strip) → Blender 5.0+ VSE [E-08]
│ ├── "has no attribute 'fcurves'" (on Action) → Blender 5.0+ slotted actions [E-09]
│ ├── "has no attribute 'displacement_method'" (on CyclesMaterial) → Blender 4.1+ [E-10]
│ ├── "has no attribute 'active_color_name'" → Blender 4.3+ AttributeGroup split [E-11]
│ ├── "has no attribute 'use_ssr'" → Blender 4.3+ EEVEE property removal [E-12]
│ ├── "has no attribute 'use_bloom'" → Blender 4.3+ EEVEE property removal [E-12]
│ └── "has no attribute 'calc_normals'" → Blender 4.0+ auto normals [E-13]
│
├── ImportError / ModuleNotFoundError?
│ ├── "No module named 'bgl'" → Blender 5.0+ BGL removal [E-14]
│ ├── "No module named 'io_scene_obj'" → Blender 4.0+ C++ IO [E-15]
│ └── "No module named 'io_mesh_ply'" → Blender 4.0+ C++ IO [E-15]
│
├── TypeError?
│ ├── On bpy.ops call with dict first arg → Blender 4.0+ context override [E-16]
│ ├── "foreach_set() invalid data type" → Blender 4.1+ validation [E-17]
│ ├── On IDProperty type mismatch → Blender 4.2+ static typing [E-18]
│ └── On __init__() argument mismatch → Blender 4.4+ super() required [E-19]
│
├── KeyError?
│ ├── "Subsurface" (on Principled BSDF) → Blender 4.0+ socket renames [E-20]
│ ├── "Specular" (on Principled BSDF) → Blender 4.0+ socket renames [E-20]
│ ├── "cycles" (on scene[]) → Blender 5.0+ dict access removal [E-21]
│ └── Node socket name not found → Version-dependent socket names [E-20]
│
├── RuntimeError?
│ ├── "Embedded ID assignment" → Blender 4.3+ PointerProperty [E-22]
│ └── "BLENDER_EEVEE" engine not found → EEVEE identifier change [E-23]
│
└── ValueError?
├── "'CUBEMAP' not in enum" → Blender 4.1+ light probe renames [E-24]
├── "'PLANAR' not in enum" → Blender 4.1+ light probe renames [E-24]
├── "'3D_UNIFORM_COLOR' not found" → Blender 4.0+ shader renames [E-25]
└── "'BLENDER_EEVEE_NEXT' not in enum" → Blender 5.0+ EEVEE revert [E-23]
2. Error Patterns: Quick Resolution Table
Blender 4.0 Breaking Errors
| Error Code | Error Message Pattern | Removed API | Replacement | Since |
|---|---|---|---|---|
| E-01 | AttributeError: 'MeshEdge' has no attribute 'bevel_weight' |
mesh.edges[i].bevel_weight |
mesh.attributes.get("bevel_weight_edge") |
4.0 |
| E-01 | AttributeError: 'MeshEdge' has no attribute 'crease' |
mesh.edges[i].crease |
mesh.attributes.get("crease_edge") |
4.0 |
| E-03 | AttributeError: 'Object' has no attribute 'face_maps' |
obj.face_maps |
Integer face attributes | 4.0 |
| E-04 | AttributeError: 'Bone' has no attribute 'layers' |
bone.layers[i] |
bone.collections |
4.0 |
| E-04 | AttributeError: 'Pose' has no attribute 'bone_groups' |
pose.bone_groups |
Bone collections + colors | 4.0 |
| E-05 | AttributeError: 'NodeTree' has no attribute 'inputs' |
NodeTree.inputs.new() |
NodeTree.interface.new_socket() |
4.0 |
| E-13 | AttributeError: 'Mesh' has no attribute 'calc_normals' |
mesh.calc_normals() |
Removed (auto-calculated) | 4.0 |
| E-15 | ModuleNotFoundError: No module named 'io_scene_obj' |
Python OBJ/PLY IO | bpy.ops.wm.obj_import/export |
4.0 |
| E-16 | TypeError: bpy.ops expects keyword arguments |
Dict context override | context.temp_override() |
4.0 |
| E-20 | KeyError: 'Subsurface' on Principled BSDF |
Old socket names | Subsurface Weight, etc. |
4.0 |
| E-25 | ValueError: '3D_UNIFORM_COLOR' not found |
3D_* shader names |
POLYLINE_* / prefix removed |
4.0 |
Blender 4.1 Breaking Errors
| Error Code | Error Message Pattern | Removed API | Replacement | Since |
|---|---|---|---|---|
| E-02 | AttributeError: 'Mesh' has no attribute 'use_auto_smooth' |
mesh.use_auto_smooth |
mesh.corner_normals + Smooth by Angle modifier |
4.1 |
| E-02 | AttributeError: 'Mesh' has no attribute 'auto_smooth_angle' |
mesh.auto_smooth_angle |
Smooth by Angle modifier | 4.1 |
| E-10 | AttributeError: 'CyclesMaterialSettings' has no attribute 'displacement_method' |
mat.cycles.displacement_method |
mat.displacement_method |
4.1 |
| E-17 | TypeError: foreach_set() invalid data type |
Silent failure on bad types | Add type validation | 4.1 |
| E-24 | ValueError: 'CUBEMAP' not in enum |
CUBEMAP/PLANAR/GRID |
SPHERE/PLANE/VOLUME |
4.1 |
Blender 4.2 Breaking Errors
| Error Code | Error Message Pattern | Removed API | Replacement | Since |
|---|---|---|---|---|
| E-18 | TypeError: IDProperty type mismatch |
Dynamic IDProperty types | Static typing enforced | 4.2 |
| E-23 | RuntimeError: 'BLENDER_EEVEE' not found (in 4.2-4.x) |
BLENDER_EEVEE |
BLENDER_EEVEE_NEXT |
4.2 |
Blender 4.3 Breaking Errors
| Error Code | Error Message Pattern | Removed API | Replacement | Since |
|---|---|---|---|---|
| E-11 | AttributeError: 'AttributeGroup*' has no attribute 'active_color_name' |
Generic AttributeGroup |
AttributeGroupMesh (type-specific) |
4.3 |
| E-12 | AttributeError: 'EEVEE' has no attribute 'use_ssr' |
40+ EEVEE legacy props | Properties removed (engine-internal) | 4.3 |
| E-22 | RuntimeError: Embedded ID assignment |
Embedded ID to PointerProperty | Do not assign embedded IDs | 4.3 |
Blender 4.4 Breaking Errors
| Error Code | Error Message Pattern | Removed API | Replacement | Since |
|---|---|---|---|---|
| E-19 | TypeError: __init__() argument mismatch |
No super().__init__() |
super().__init__(*args, **kwargs) |
4.4 |
Blender 5.0 Breaking Errors
| Error Code | Error Message Pattern | Removed API | Replacement | Since |
|---|---|---|---|---|
| E-14 | ModuleNotFoundError: No module named 'bgl' |
import bgl |
import gpu + gpu.state.* |
5.0 |
| E-06 | AttributeError: 'Brush' has no attribute 'sculpt_tool' |
brush.sculpt_tool |
brush.sculpt_brush_type |
5.0 |
| E-07 | AttributeError: 'Scene' has no attribute 'node_tree' |
scene.node_tree (compositor) |
scene.compositing_node_group |
5.0 |
| E-08 | AttributeError: 'Strip' has no attribute 'end_frame' |
strip.end_frame |
strip.length |
5.0 |
| E-09 | AttributeError: 'Action' has no attribute 'fcurves' |
action.fcurves (legacy) |
Slotted Actions channelbag API | 5.0 |
| E-21 | KeyError: 'cycles' on scene['cycles'] |
Dict access to RNA props | scene.cycles.samples (attribute) |
5.0 |
3. Deprecation Timeline
ALWAYS check this timeline before using any API. If the current Blender version is past the removal date, the API WILL raise an error.
| API | Deprecated | Removed | Warning Period |
|---|---|---|---|
| Context override dicts | 3.2 | 4.0 | 3.2 → 3.6 (4 releases) |
mesh.calc_normals() |
3.4 | 4.0 | 3.4 → 3.6 (2 releases) |
MeshEdge.bevel_weight / .crease |
3.4 | 4.0 | 3.4 → 3.6 (2 releases) |
NodeTree.inputs/outputs |
3.4 | 4.0 | 3.4 → 3.6 (2 releases) |
3D_UNIFORM_COLOR shader |
3.4 | 4.0 | 3.4 → 3.6 (2 releases) |
bgl module |
3.5 | 5.0 | 3.5 → 4.x (long, 9+ releases) |
mesh.use_auto_smooth |
4.0 | 4.1 | 4.0 only (1 release) |
Light probe CUBEMAP/PLANAR/GRID |
4.0 | 4.1 | 4.0 only (1 release) |
bl_info dict (for extensions) |
4.2 | Ongoing | Still works as legacy addon |
BLENDER_EEVEE identifier |
4.2 | 4.2 (temp) | Renamed to _NEXT, reverted in 5.0 |
| EEVEE legacy properties (40+) | 4.2 | 4.3 | 4.2 only (1 release) |
bpy.types.AttributeGroup (generic) |
4.2 | 4.3 | 4.2 only (1 release) |
bpy.types.Sequence (VSE) |
4.3 | 4.4 | 4.3 only (1 release) |
action.fcurves (legacy) |
4.4 | 5.0 | 4.4 → 4.5 (2 releases) |
Image.bindcode / gl_load() |
4.0 | 5.0 | 4.0 → 4.x (long) |
scene['cycles'] dict access |
4.2 | 5.0 | 4.2 → 4.x |
scene.node_tree (compositor) |
4.2 | 5.0 | 4.2 → 4.x |
| VSE time property names | 5.1 | 6.0 | 5.1 → 5.x (future) |
4. Diagnostic Patterns
Pattern 1: Identify Version from Error
When a user reports an error without specifying their Blender version, ALWAYS determine the version first:
# Blender 3.x / 4.x / 5.x: Print diagnostic info
import bpy
print(f"Blender: {bpy.app.version}")
print(f"Python: {bpy.app.version_string}")
print(f"Cycle: {bpy.app.version_cycle}")
Pattern 2: Version-Safe Error Recovery
ALWAYS use hasattr() for graceful degradation. NEVER catch AttributeError silently.
# Blender 3.x / 4.x / 5.x: Version-safe accessor with explicit fallback
import bpy
def get_bevel_weight(mesh, edge_index):
"""Get edge bevel weight with version-safe fallback."""
if bpy.app.version >= (4, 0, 0):
attr = mesh.attributes.get("bevel_weight_edge")
if attr:
return attr.data[edge_index].value
return 0.0
else:
return mesh.edges[edge_index].bevel_weight
Pattern 3: Multi-Version Compatibility Wrapper
For addons targeting multiple Blender versions, use a compatibility module:
# Blender 3.x / 4.x / 5.x: compat.py module pattern
import bpy
BLENDER_4 = bpy.app.version >= (4, 0, 0)
BLENDER_41 = bpy.app.version >= (4, 1, 0)
BLENDER_42 = bpy.app.version >= (4, 2, 0)
BLENDER_43 = bpy.app.version >= (4, 3, 0)
BLENDER_44 = bpy.app.version >= (4, 4, 0)
BLENDER_5 = bpy.app.version >= (5, 0, 0)
BLENDER_51 = bpy.app.version >= (5, 1, 0)
5. Critical Rules
- NEVER suppress
DeprecationWarningin Blender scripts — it hides migration signals. - NEVER use
try/except AttributeErroras a version check — usebpy.app.versionorhasattr(). - ALWAYS check the deprecation timeline BEFORE using any Blender API.
- ALWAYS test addons on the OLDEST supported version, not just the newest.
- NEVER assume backward compatibility of
.blendfiles across major API rewrites (Grease Pencil 4.3, Slotted Actions 4.4, Compositor 5.0). - ALWAYS restore
gpu.stateto defaults at the end of draw callbacks. - NEVER use
bglin any new code — it is REMOVED in Blender 5.0. - ALWAYS use
context.temp_override()instead of dict overrides in Blender 4.0+.
6. Reference Links
- references/methods.md — Error diagnosis functions, version detection API, compatibility checking utilities
- references/examples.md — Error-to-fix migration code for each error pattern (E-01 through E-25)
- references/anti-patterns.md — Version compatibility mistakes that cause errors, with explanations