[Bug]: Docker API hook manager crashes for all kind of user-provided hooks

[przemekmatusiak]

crawl4ai version

v8.0.0

Expected Behavior

Providing a hook via API request body should not cause hook_manager.py error before the hook code execution.

Current Behavior

Even the simplest hook, like this one

async def hook(page, context, **kwargs):
    return page

is causing the hook validation errors in the logs:

2026-03-28 09:32:15,743 - hook_manager - ERROR - Hook compilation failed for on_page_context_created: __import__ not found
2026-03-28 09:32:15,743 - hook_manager - WARNING - Hook validation errors: [{'hook_point': 'on_page_context_created', 'error': 'Failed to compile hook function - check syntax and structure', 'code_preview': '\nasync def hook(page, context, **kwargs):\n    return page\n'}]
2026-03-28 09:32:15,743 - api - INFO - Hooks attachment status: failed

hooks part of the API response:

(...)
"hooks": {
        "status": {
            "status": "failed",
            "attached_hooks": [],
            "validation_errors": [
                {
                    "hook_point": "on_page_context_created",
                    "error": "Failed to compile hook function - check syntax and structure",
                    "code_preview": "\nasync def hook(page, context, **kwargs):\n    return page\n"
                }
            ],
            "total_hooks_provided": 1,
            "successfully_attached": 0,
            "failed_validation": 1
        },
        "execution_log": [],
        "errors": [
            {
                "hook_point": "on_page_context_created",
                "error": "Failed to compile hook: __import__ not found",
                "type": "compilation_error",
                "traceback": "Traceback (most recent call last):\n  File \"/app/hook_manager.py\", line 144, in compile_hook\n    exec(\"import asyncio\", namespace)\n  File \"<string>\", line 1, in <module>\nImportError: __import__ not found\n"
            }
        ],
        "summary": {
            "total_executions": 0,
            "successful": 0,
            "failed": 0,
            "timed_out": 0,
            "success_rate": 0,
            "total_errors": 1
        }
    }
}

Decoded traceback:

Traceback (most recent call last):
  File "/app/hook_manager.py", line 144, in compile_hook
    exec("import asyncio", namespace)
  File "<string>", line 1, in <module>
ImportError: __import__ not found

I think this is caused by the change in #1712, which removed the import ... option for hooks. However, in the next lines, the hook_manager tries to import some commonly used libraries, and asyncio appears to be the first.

Is this reproducible?

Yes

Inputs Causing the Bug

curl -X POST \
  http://localhost:11235/crawl \
  -H 'Content-Type: application/json' \
  -d '{
    "urls": ["https://www.reddit.com/r/devops/comments/1s51xj8/docker_vs_firecracker_for_browser_sandboxing/"],
    "hooks": {"timeout": 30, "code": {"on_page_context_created": "\nasync def hook(page, context, **kwargs):\n    return page\n"} }
  }'

Steps to Reproduce

Code snippets

                'getattr', 'hasattr', 'setattr', 'callable', 'iter', 'next',
                '__import__', '__build_class__'  # Required for exec        ---- #⚠️ '__import__' removed in v0.8.0
                '__build_class__'  # Required for class definitions in exec
            ]

            for name in allowed_builtins:
                if hasattr(builtins, name):
                    safe_builtins[name] = getattr(builtins, name)

            namespace = {
                '__name__': f'user_hook_{hook_point}',
                '__builtins__': safe_builtins
            }

            # Add commonly needed imports
            exec("import asyncio", namespace)        ---- #⚠️ crashes here
            exec("import json", namespace)

OS

Linux

Python version

3.12.13

Browser

No response

Browser version

No response

Error logs & Screenshots (if applicable)

No response

[hafezparast]

Thanks for the clear report @przemekmatusiak — you nailed the root cause.

PR #1712 removed __import__ from the safe builtins (correctly, for security), but the hook compiler still used exec("import asyncio", namespace) on lines 143-147 which requires __import__ to work. This breaks all user-provided hooks, not just ones that try to import.

Fix in #1879:

• Replace exec("import ...") with direct module injection (namespace['asyncio'] = asyncio, etc.) — no __import__ needed
• Also added standard exception classes (ValueError, TypeError, KeyError, etc.) to the safe builtins, so hooks can use try/except properly
• __import__ remains blocked — security intent of Release v0.8.0: Crash Recovery, Prefetch Mode & Security Fixes #1712 is preserved

[haileyholland651-arch]

Ahh yeah, that lines up. Makes sense that removing __import__ broke the internal exec("import ...") path — good catch. The module injection approach in #1879 seems like the right fix, and nice that it keeps the security model intact. Thanks for the quick turnaround on this 👍

…

On Sat, Mar 28, 2026, 8:39 AM Maysam Hafezparast ***@***.***> wrote: *hafezparast* left a comment (unclecode/crawl4ai#1878) <#1878 (comment)> Thanks for the clear report @przemekmatusiak <https://github.com/przemekmatusiak> — you nailed the root cause. PR #1712 <#1712> removed __import__ from the safe builtins (correctly, for security), but the hook compiler still used exec("import asyncio", namespace) on lines 143-147 which requires __import__ to work. This breaks *all* user-provided hooks, not just ones that try to import. Fix in #1879 <#1879>: - Replace exec("import ...") with direct module injection (namespace['asyncio'] = asyncio, etc.) — no __import__ needed - Also added standard exception classes (ValueError, TypeError, KeyError, etc.) to the safe builtins, so hooks can use try/except properly - __import__ remains blocked — security intent of #1712 <#1712> is preserved — Reply to this email directly, view it on GitHub <#1878?email_source=notifications&email_token=CAX5D35OLR4F5LU2XGGRDKT4S7IZ5A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMJUHAYDSMRQGU2KM4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSWGM33PORSXEX3DNRUWG2Y#issuecomment-4148092054>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/CAX5D36NMCBH5QDGTVIY52T4S7IZ5AVCNFSM6AAAAACXDB2DOWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DCNBYGA4TEMBVGQ> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[liamoss1231-ai]

Thanks for raising this issue! I can see how the change in #1712 might have impacted the hook compilation process, especially since the removal of dynamic imports like __import__ is preventing the hook from compiling correctly. On Mon, Mar 30, 2026, 6:29 PM haileyholland651-arch < ***@***.***> wrote:

…

*haileyholland651-arch* left a comment (unclecode/crawl4ai#1878) <#1878 (comment)> Ahh yeah, that lines up. Makes sense that removing __import__ broke the internal exec("import ...") path — good catch. The module injection approach in #1879 seems like the right fix, and nice that it keeps the security model intact. Thanks for the quick turnaround on this 👍 On Sat, Mar 28, 2026, 8:39 AM Maysam Hafezparast ***@***.***> wrote: > *hafezparast* left a comment (unclecode/crawl4ai#1878) > < #1878 (comment)> > > Thanks for the clear report @przemekmatusiak > <https://github.com/przemekmatusiak> — you nailed the root cause. > > PR #1712 <#1712> removed > __import__ from the safe builtins (correctly, for security), but the hook > compiler still used exec("import asyncio", namespace) on lines 143-147 > which requires __import__ to work. This breaks *all* user-provided hooks, > not just ones that try to import. > > Fix in #1879 <#1879>: > > - Replace exec("import ...") with direct module injection (namespace['asyncio'] > = asyncio, etc.) — no __import__ needed > - Also added standard exception classes (ValueError, TypeError, > KeyError, etc.) to the safe builtins, so hooks can use try/except > properly > - __import__ remains blocked — security intent of #1712 > <#1712> is preserved > > — > Reply to this email directly, view it on GitHub > < #1878?email_source=notifications&email_token=CAX5D35OLR4F5LU2XGGRDKT4S7IZ5A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMJUHAYDSMRQGU2KM4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSWGM33PORSXEX3DNRUWG2Y#issuecomment-4148092054>, > or unsubscribe > < https://github.com/notifications/unsubscribe-auth/CAX5D36NMCBH5QDGTVIY52T4S7IZ5AVCNFSM6AAAAACXDB2DOWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DCNBYGA4TEMBVGQ> > . > You are receiving this because you are subscribed to this thread.Message > ID: ***@***.***> > — Reply to this email directly, view it on GitHub <#1878?email_source=notifications&email_token=CAXZQSPVSECQ77BDJZQLWBT4TL7OPA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMJVHA3TQOJWGI32M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSWGM33PORSXEX3DNRUWG2Y#issuecomment-4158789627>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/CAXZQSPCBMEDAOOCF5SXOC34TL7OPAVCNFSM6AAAAACXDB2DOWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DCNJYG44DSNRSG4> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>