blender-errors-context

Blender Context Errors: Diagnosis and Resolution

Purpose

This skill enables diagnosis and resolution of Blender Python context errors. Context errors are the most common category of Blender scripting failures. They occur when code accesses bpy.context members or calls bpy.ops operators in situations where the required context is unavailable, restricted, or incorrectly configured.

Scope

RuntimeError from restricted context access (handlers, timers, draw callbacks)
Operator poll() failures and incorrect context for bpy.ops calls
Context override removal in Blender 4.0+ and temp_override() migration
Modal operator context issues
Context-dependent attribute access (bpy.context.active_object, bpy.context.edit_object)
Stale references after undo, data modification, or mode changes

Version coverage: Blender 3.x, 4.x, 5.x. Version-breaking changes are marked explicitly.

Dependencies: This skill builds on blender-core-api (context system basics) and blender-syntax-operators (operator patterns).

1. Context Error Categories

1.1 RuntimeError: Restricted Context

When: Code runs in a context where bpy.context is partially or fully unavailable.

Restricted contexts:

depsgraph_update_post / depsgraph_update_pre handlers
render_pre / render_post / render_write handlers
draw() methods of bpy.types.Panel, bpy.types.Header, bpy.types.Menu
bpy.app.timers callbacks
Background threads (NEVER access bpy.context from threads)

Error messages:

RuntimeError: restricted context element 'active_object'
RuntimeError: Calling operator "bpy.ops.object.select_all" error, can't modify blend data in this state

Rule: In restricted contexts, use bpy.data for read-only access. NEVER call bpy.ops or modify blend data. To defer work to a safe context, use bpy.app.timers.register().

# Blender 3.2+
import bpy

def my_handler(scene, depsgraph):
    # WRONG: bpy.context.active_object raises RuntimeError
    # WRONG: bpy.ops.object.delete() raises RuntimeError

    # CORRECT: read-only access via bpy.data
    obj = bpy.data.objects.get("Cube")
    if obj is not None:
        print(obj.location)

    # CORRECT: defer modifications to a timer
    def deferred():
        bpy.data.objects["Cube"].location.x += 1.0
        return None  # do not repeat
    bpy.app.timers.register(deferred)

bpy.app.handlers.depsgraph_update_post.append(my_handler)

1.2 Operator poll() Failures

When: An operator's poll() classmethod returns False because required context conditions are not met.

Error message:

RuntimeError: Operator bpy.ops.object.mode_set.poll() failed, context is incorrect

Common causes:

Operator	Required context
`bpy.ops.object.mode_set()`	Active object exists, is visible, is selectable
`bpy.ops.mesh.subdivide()`	Active object is mesh, in Edit Mode
`bpy.ops.object.parent_set()`	2+ objects selected, one active
`bpy.ops.uv.unwrap()`	Active mesh in Edit Mode, UV map exists
`bpy.ops.object.convert()`	Active object exists, correct type

Rule: ALWAYS check poll() before calling an operator, OR set up the required context explicitly.

# Blender 3.2+
import bpy

obj = bpy.data.objects.get("Cube")
if obj is None:
    raise RuntimeError("Object 'Cube' not found")

# Ensure context: select and activate
bpy.context.view_layer.objects.active = obj
obj.select_set(True)

# Check poll before calling
if bpy.ops.object.mode_set.poll():
    bpy.ops.object.mode_set(mode='EDIT')

1.3 Context Override Errors (Version-Critical)

BREAKING CHANGE in Blender 4.0: Dictionary-based context overrides are REMOVED.

# Blender 3.x ONLY: REMOVED in 4.0
override = bpy.context.copy()
override['area'] = area
override['region'] = region
bpy.ops.view3d.camera_to_view(override)  # TypeError in 4.0+

Blender 3.2+ (REQUIRED in 4.0+): Use bpy.context.temp_override().

# Blender 3.2+ (works in 3.2, 3.3, ..., 4.0, 4.1, ..., 5.x)
import bpy

area = next(a for a in bpy.context.screen.areas if a.type == 'VIEW_3D')
region = next(r for r in area.regions if r.type == 'WINDOW')

with bpy.context.temp_override(area=area, region=region):
    bpy.ops.view3d.camera_to_view()

Rule: ALWAYS use bpy.context.temp_override() for context overrides. NEVER use dictionary-based overrides — they fail silently in 3.6 and raise TypeError in 4.0+.

1.4 Modal Operator Context

When: Modal operators lose context between invoke() and modal() calls, or access area/region data that changes between frames.

Rule: Store required context references during invoke(). Do NOT rely on bpy.context.area or bpy.context.region persisting in modal().

# Blender 3.2+
import bpy

class EXAMPLE_OT_modal(bpy.types.Operator):
    bl_idname = "example.modal_op"
    bl_label = "Modal Example"

    def invoke(self, context, event):
        # Store references during invoke
        self._area = context.area
        self._region = context.region
        context.window_manager.modal_handler_add(self)
        return {'RUNNING_MODAL'}

    def modal(self, context, event):
        if event.type == 'ESC':
            return {'CANCELLED'}
        # Use stored references, not context.area
        if self._area.type != 'VIEW_3D':
            return {'CANCELLED'}
        return {'PASS_THROUGH'}

1.5 Context-Dependent Attribute Access

When: Code accesses bpy.context attributes that are only available in specific editor types or modes.

Attributes with context requirements:

Attribute	Requires
`context.edit_object`	Object in Edit Mode
`context.active_bone`	Armature in Edit Mode
`context.active_pose_bone`	Armature in Pose Mode
`context.sculpt_object`	Object in Sculpt Mode
`context.image_paint_object`	Object in Texture Paint Mode
`context.selected_editable_bones`	Armature in Edit Mode
`context.visible_pose_bones`	Armature in Pose Mode

Rule: ALWAYS check mode before accessing mode-specific context attributes. These attributes return None or raise AttributeError when the mode does not match.

# Blender 3.2+
import bpy

# WRONG: may be None if not in Edit Mode
# verts = bpy.context.edit_object.data.vertices

# CORRECT: check mode first
obj = bpy.context.active_object
if obj is not None and obj.mode == 'EDIT':
    edit_obj = bpy.context.edit_object
    # work with edit_obj

2. Stale Reference Errors

2.1 Undo Invalidates All References

When: After bpy.ops.ed.undo() or user Ctrl+Z, ALL previously stored references to Blender data become invalid.

Error message:

ReferenceError: StructRNA of type Object has been removed

Rule: NEVER store persistent references to bpy.types instances across operations that may trigger undo. Re-fetch by name after undo.

# Blender 3.2+
import bpy

# WRONG: reference becomes stale after undo
obj = bpy.data.objects["Cube"]
bpy.ops.ed.undo()
print(obj.location)  # ReferenceError

# CORRECT: re-fetch after undo
obj_name = "Cube"
bpy.ops.ed.undo()
obj = bpy.data.objects.get(obj_name)
if obj is not None:
    print(obj.location)

2.2 Data Modification Invalidates References

When: Operations that add or remove data blocks (objects, meshes, materials) may invalidate existing Python references to the same collection.

Rule: After any operation that modifies bpy.data collections, re-fetch references by name. NEVER iterate a collection while modifying it.

# Blender 3.2+
import bpy

# WRONG: modifying collection during iteration
for obj in bpy.data.objects:
    bpy.data.objects.remove(obj)  # invalidates iterator

# CORRECT: collect names first, then remove
names = [obj.name for obj in bpy.data.objects if obj.type == 'MESH']
for name in names:
    obj = bpy.data.objects.get(name)
    if obj is not None:
        bpy.data.objects.remove(obj)

2.3 Mode Change Invalidates Mesh References

When: Switching between Object Mode and Edit Mode invalidates bmesh.from_edit_mesh() references and mesh data access patterns.

Rule: ALWAYS obtain fresh mesh/bmesh references after mode changes. Free BMesh instances when done.

# Blender 3.2+
import bpy
import bmesh

obj = bpy.context.active_object
bpy.ops.object.mode_set(mode='EDIT')

bm = bmesh.from_edit_mesh(obj.data)
bm.verts.ensure_lookup_table()

# ... perform edits ...

bmesh.update_edit_mesh(obj.data)
# Do NOT call bm.free() for from_edit_mesh: Blender manages it

bpy.ops.object.mode_set(mode='OBJECT')
# bm is now INVALID: do not use

3. Resolution Decision Tree

When encountering a context error, follow this sequence:

1. Is the error "restricted context element"?
   YES → Code runs in a handler, timer, or draw callback.
         → Use bpy.data for read-only access.
         → Defer modifications with bpy.app.timers.register().

2. Is the error "poll() failed"?
   YES → Check operator requirements (mode, selection, active object).
         → Set up context: activate object, set mode, ensure selection.
         → Use temp_override() if area/region context is needed.

3. Is the error about context overrides (TypeError)?
   YES → Blender 4.0+ removed dict-based overrides.
         → Migrate to bpy.context.temp_override().
         → See §1.3 for migration pattern.

4. Is the error "StructRNA has been removed"?
   YES → Reference invalidated by undo or data modification.
         → Re-fetch by name from bpy.data.
         → See §2 for patterns.

5. Is the attribute None unexpectedly?
   YES → Context attribute requires specific mode or editor type.
         → Check mode before access.
         → See §1.5 for attribute requirements.

4. Version Migration Reference

4.0 Context Override Removal

Aspect	Blender 3.x	Blender 4.0+
Context override syntax	`op(override_dict, ...)`	REMOVED — TypeError
Recommended syntax	`temp_override()` (3.2+)	`temp_override()` (required)
`bpy.context.copy()` for overrides	Works but deprecated	REMOVED

temp_override() Availability

Blender Version	`temp_override()`	Dict overrides
3.0–3.1	NOT available	Works
3.2–3.6	Available	Works (deprecated)
4.0+	Required	REMOVED

Version Detection Pattern

# Blender 3.2+
import bpy

def call_with_override(area, region, op_func, **kwargs):
    """Call operator with context override, version-aware."""
    if bpy.app.version >= (3, 2, 0):
        with bpy.context.temp_override(area=area, region=region):
            return op_func(**kwargs)
    else:
        override = bpy.context.copy()
        override['area'] = area
        override['region'] = region
        return op_func(override, **kwargs)

Note: The version-detection pattern above is provided for migration of legacy code. For new code, ALWAYS target Blender 3.2+ and use temp_override() exclusively.

5. Threading Rules

Rule: NEVER access bpy.context, bpy.ops, or modify bpy.data from background threads.

Error:

RuntimeError: can't modify blend data outside main thread

Resolution: Use bpy.app.timers.register() to schedule work on the main thread.

# Blender 3.2+
import bpy
import threading

def background_work():
    result = expensive_computation()

    def apply_result():
        bpy.data.objects["Cube"].location.x = result
        return None  # do not repeat
    bpy.app.timers.register(apply_result)

thread = threading.Thread(target=background_work)
thread.start()

6. Quick Reference: Error Message Index

Error Message	Section	Resolution
`RuntimeError: restricted context element '...'`	§1.1	Use `bpy.data`, defer with timers
`RuntimeError: Operator ... poll() failed`	§1.2	Set up context, check poll()
`TypeError: ... takes N positional arguments` (4.0+)	§1.3	Migrate to `temp_override()`
`ReferenceError: StructRNA of type ... has been removed`	§2.1	Re-fetch by name
`RuntimeError: can't modify blend data outside main thread`	§5	Use `bpy.app.timers.register()`
`AttributeError: 'NoneType' has no attribute ...` on context	§1.5	Check mode before access

References

references/methods.md — Context-related API signatures
references/examples.md — Working error resolution examples
references/anti-patterns.md — Common context mistakes with corrections

About this skill