python-nested-import-nameerror

Python Nested Import NameError Bug Pattern

Python 함수 내부에서 import json 또는 import json as X를 실행하면, 같은 함수 내 모든 json 참조가 local variable가 됨. 선언보다 앞에서 json.dumps() 등을 호출하면 → UnboundLocalError.

Root Cause — Python Lexical Scoping

Python 컴파일러가 함수 전체를 훑는다. 함수 어딘가에서 import json as X를 보면, 해당 함수 스코프의 json 이름을 local variable로 등록한다. 이후 json.dumps()가 호출되더라도, local json은 아직 값이 할당되지 않았으므로 → UnboundLocalError.

def run_conversation(self):
    # ...
    if isinstance(raw, dict):
        assistant_message.content = (
            raw.get("text", "")
            or raw.get("content", "")
            or json.dumps(raw)   # ❌ line 10646 — local `json` 아직 없음
        )
    # ...
    def inner():
        import json as _json_mod  # line 10929 — 이 한 줄이
        _json_mod.dumps(...)       # `json` 이름을 local로 만듦

# Error: cannot access local variable 'json' where it is not associated with a value

The Fix — module-level import 우선

import json  # file top — module-level (line 29)

def run_conversation(self):
    json.dumps(raw)  # ✅ module-level `json` 사용

Applied Fixes in run_agent.py

2026-05-30 fix — run_conversation() 내부 4곳 수정:

줄	수정 전	수정 후	이유
10929	import json as _json_mod	# json is module-level (line 29) 주석 처리	nested import 제거 — json 이름 local로 shadowing됨
10934	_json_mod.dumps(args)	json.dumps(args)	module-level json 직접 사용
10944	_json_mod.loads(args)	json.loads(args)	module-level json 직접 사용
11548	import os, json	# os, json are module-level 주석 처리	nested import 제거

주의: 이전 수정(2026-05-29)에서 import json as _json_mod를 주석 처리하고 json.dumps() 사용으로 바꿨지만, 같은 함수 스코프 내의 json.loads() 호출은 여전히 _json_mod.loads()로 남아있음 → NameError: name '_json_mod' is not defined 발생

정답: 모든 nested import json 제거 → module-level import json (line 29) 하나만 사용

Detection Commands

# nested import json 패턴 찾기
grep -n "import json\|import os, json" ~/.{{AGENT_NAME_LOWER}}/source/{{AGENT_NAME_LOWER}}-agent/run_agent.py

# 함수 내부 import json AST로 정확히 찾기
python3 -c "
import ast, sys
with open(sys.argv[1]) as f:
    tree = ast.parse(f.read())
for node in ast.walk(tree):
    if isinstance(node, ast.FunctionDef):
        local = [n for n in ast.walk(node) if isinstance(n, (ast.Import, ast.ImportFrom)) and any(a.name == 'json' for a in n.names)]
        if local:
            print(f'{node.name}: line {local[0].lineno} — {ast.unparse(local[0])}')
" ~/.{{AGENT_NAME_LOWER}}/source/{{AGENT_NAME_LOWER}}-agent/run_agent.py

# _json_mod 잔여 확인
grep -n "_json_mod" ~/.{{AGENT_NAME_LOWER}}/source/{{AGENT_NAME_LOWER}}-agent/run_agent.py