문제 해결

빠른 찾기

실행이 안 되면: 실행 오류
플로우 수정 후 깨지면: 코드 수정 후 오류 (그래프/노드)
Registry 호출이 실패하면: Registry LLM 오류
메모리가 이어지지 않으면: 세션 메모리 오류
PgBouncer 뒤에서 1시간 후 conn 에러: PostgreSQL / PgBouncer 관련
prompt 변수 치환이 안 되면: Prompt Template / Binding 오류
폐쇄망 준비/패키징이 실패하면: 폐쇄망 준비 오류
설치/환경 문제면: 환경 설정 오류

SDK 로그 레벨 (LOG_LEVEL)

.env의 LOG_LEVEL 한 줄로 로그 양을 조절합니다. 템플릿 main.py가 호출하는 setup_logging(settings) 덕분에 SDK(llamon_agent.*)와 사용자 코드(app.*) 로그가 모두 이 레벨을 따라 stderr로 출력됩니다.

값	용도
`DEBUG`	전체 디버그 로그 (routing, MCP, 노드, guardrail + 사용자 `app.*`)
`INFO`	주요 동작 로그
`WARNING`	경고만 (기본값)
`ERROR`	에러만

LOG_LEVEL=DEBUG

사용자 노드 코드에서는 표준 방식 그대로 쓰면 됩니다 — logger = logging.getLogger(__name__). 별도 설정이나 basicConfig 호출은 필요 없습니다.

uvicorn 서버 로그(시작 배너·요청 로그)는 별도 설정입니다 → .env의 UVICORN_LOG_LEVEL(기본 info). LOG_LEVEL과 독립이라 따로 조절할 수 있습니다.
DEBUG에서도 httpx/httpcore(HTTP 전송) 로그는 폭주를 막기 위해 WARNING으로 낮춰 둡니다. 전부 보려면 main.py에서 setup_logging(settings, quiet=())로 끄세요.
trace 로그는 TRACE_CONSOLE_ENABLED로 켜지는 stdout 별도 채널입니다.

실행 오류

알 수 없는 템플릿 오류:
- llamon agent: agent-general, agent-structured, agent-local, agent-openai, agent-anthropic
- llamon flow: flow-seq, flow-parallel, flow-route, flow-http

PostgreSQL 연결 실패 — traceback 한 줄로 원인을 구분하세요:

Traceback 핵심 경로	원인	수정할 변수
`outbound/memory/backends.py` → `langgraph/checkpoint/postgres/aio.py`	세션 메모리 checkpointer 부팅 실패 (서버가 아예 안 뜸)	`POSTGRES_MEMORY_DSN`
`app/nodes.py` → `asyncpg/_asyncio.py`	비즈니스 노드 실행 중 실패 (서버는 떴고 요청 처리 중 오류)	`POSTGRES_URL`

두 DSN은 서로 영향을 주지 않습니다. 한쪽을 바꿔도 다른 쪽은 그대로입니다.

--memory postgres 실행 방법: uv run llamon run .으로 띄우면 POSTGRES_MEMORY_DSN이 @postgres:5432/...로 자동으로 덮어써집니다. 외부 DB를 쓰려면 .env의 값을 실제 host로 교체하세요.
uv run python main.py 직접 실행 → DB 연결 실패: Docker 없이 실행되므로 postgres 메모리 모드에서 즉시 오류납니다. uv run llamon run .을 사용하세요.
실행 대상 디렉토리에 compose 파일이 없습니다: llamon run은 기본적으로 현재 폴더의 docker-compose.local.yml을 사용합니다.
- 해결: 프로젝트 루트에서 실행하거나 --compose-file로 파일명을 명시하세요.

코드 수정 후 오류 (그래프/노드)

증상	원인	해결
`TypeError` (keyword-only argument)	`registry_node` 함수를 graph.py에 직접 `.node()` 등록	클로저 `async def _name(state): return await name(state, name_url=url)` 로 래핑 후 등록
`TypeError: object NoneType can't be used in 'await'`	노드를 `async def` 대신 `def`로 선언	모든 노드 함수는 `async def` 필수
노드가 `None`을 반환하여 AttributeError	노드 함수에서 `return` 누락	`return {"output": ...}` 항상 명시
서버 시작 즉시 오류	`build_graph()`에서 `return` 누락	`return (GraphBuilder()...build())` 확인
config 자리표시자 오류	`<YOUR_...>` 미교체 (config.py, nodes.py 등)	`llamon doctor .` 로 사전 확인
미완성 registry_node	graph.py에 `# TODO: .node(` 주석 잔존	`llamon doctor .` → todo_node warn 확인

LLM tool 선택 문제

증상	원인	해결
LLM이 불필요한 tool을 호출 / 잘못된 tool 선택	ReAct의 자율 판단으로 인한 변동성	규제/민감 도메인이라면 `@deterministic_tool` 로 규칙 기반 확정 호출 고려
LLM이 같은 tool을 반복 호출해 `GraphRecursionError` 발생	`REACT_MAX_ITERATIONS` 상한 도달	`.env`의 `REACT_MAX_ITERATIONS` 값을 늘리거나 (ReAct 반복 상한), prompt로 “한 번만 호출” 지시
LLM이 deterministic 결과를 무시하고 다시 동일 tool 호출	system prompt에 우선 사용 지시 없음	system prompt에 “확정 호출 결과가 있으면 우선 사용” 명시

Registry LLM 오류

증상	원인	해결
`404 {"loc":"GATEWAY","message":"서비스없음"}`	`config.py`의 Registry model ID 또는 Registry 쪽 모델 연결이 잘못됨	`LLMConfig(id=...)`에 넣은 model ID와 Registry 모델 구성을 다시 확인
`404 {"loc":"PROVIDER","message":"서비스없음"}`	provider는 살아 있으나 요청 프로토콜이 맞지 않음	Registry `provider_type.code`가 `PROVIDER_VLLM`인지 확인하고 SDK 최신 버전 사용
`langchain_ollama` 경로에서 Registry provider 호출 실패	Ollama provider가 아닌데 Ollama adapter로 연결됨	`PROVIDER_VLLM`/`PROVIDER_OPENAI`는 OpenAI 호환 adapter로 처리되는 버전으로 업데이트

확인 순서

Registry provider 조회에서 provider_type.code를 확인합니다.
Registry model 조회에서 LLMConfig(id=...)에 넣은 model ID가 올바른지 확인합니다.
PROVIDER_VLLM이면 모델 endpoint가 보통 /v1 계열 OpenAI 호환 API인지 확인합니다.

예시:

provider_type.code = "PROVIDER_VLLM"
model url = "http://10.1.1.70:8005/v1"

이 경우 SDK는 OllamaAdapter가 아니라 OpenAIAdapter를 사용해야 정상입니다.

세션 메모리 오류

증상	원인	해결
같은 사용자인데 대화가 이어지지 않음	A2A 요청에 `message.contextId` 누락	모든 요청에서 같은 `contextId`를 전달
`params.metadata.thread_id`를 보냈는데 메모리 미동작	세션 키는 `message.contextId`만 사용	`thread_id` 대신 `message.contextId` 사용
`message/send`는 되는데 `message/stream`에서 세션이 끊김	stream 요청마다 다른 `contextId` 사용	`message/stream`에도 동일한 `contextId` 사용

PostgreSQL / PgBouncer 관련

v0.2.1+ 부터 SDK는 PgBouncer session 모드 전제로 동작합니다. transaction 모드 사용 시 prepared statement 캐시가 깨지면서 무작위로 쿼리가 실패합니다.

증상	원인	해결
컨테이너 기동 후 정확히 1시간 뒤 첫 메시지에서 `psycopg.OperationalError` / 죽은 conn 에러	PgBouncer `SERVER_LIFETIME=3600s`이 백엔드 conn 강제 종료	v0.2.1+ 로 업그레이드 — SDK가 `max_lifetime=1800s`로 먼저 회전
`prepared statement "__asyncpg_stmt_X__" does not exist`	PgBouncer가 transaction 모드로 운영됨	PgBouncer를 `POOL_MODE=session`으로 변경, 또는 SDK의 `_ASYNCPG_STATEMENT_CACHE_SIZE=0`으로 변경
`DELETE /memory/threads?all=true` 가 `asyncio.TimeoutError` 로 실패	천 개 이상 thread 일괄 삭제가 admin timeout(120s) 초과	thread_id 100개씩 배치로 분할 호출, 또는 `_ASYNCPG_ADMIN_COMMAND_TIMEOUT` 상수 증설 후 빌드
PgBouncer pool saturation (`cl_waiting > 0` in `SHOW POOLS`)	동시 활성 에이전트 수 × 5 > `DEFAULT_POOL_SIZE`	PgBouncer `DEFAULT_POOL_SIZE`를 250 이상으로 증설 (Postgres `max_connections=300` 한도 내)
`pg_stat_activity`에 죽은 conn 다수 누적	SDK 컨테이너 비정상 종료 시 `close()` 호출 안 됨	`SERVER_IDLE_TIMEOUT=600s` 후 자동 정리 — 즉시 정리 필요하면 PgBouncer admin DB에서 `RELOAD`

자세한 운영 가이드와 권장 PgBouncer 설정은 PgBouncer 호환성 참조.

Prompt Template / Binding 오류

증상	원인	해결
`{{job}}` 가 그대로 출력됨	binding 미설정 또는 source 오타	`input`, `context.userId`, `const.Analyst` 같은 source를 명시
Studio에서 저장 후 prompt bindings가 사라짐	구버전 Studio/API 사용	최신 버전에서 Agent Editor 또는 Graph Node 패널로 다시 저장
Registry Prompt는 있는데 변수값이 안 들어감	Prompt ID만 설정하고 `bindings`를 비워둠	`PromptConfig(..., bindings={...})` 추가
`env.X` 가 비어 있음	허용되지 않은 환경변수 prefix 사용	`LLAMON_`, `PROMPT_`, `TMPL_` prefix 사용
단독 agent에서 `node.xxx.output` 가 비어 있음	`node.*` 는 flow 전용 source	단독 agent에서는 `input`, `context.`, `env.`, `const.*` 만 사용

params.metadata.userId, params.metadata.sessionId 는 기본적으로 observability/Langfuse correlation 값입니다.
프롬프트에 넣으려면 명시적으로 아래처럼 바인딩해야 합니다.

PromptConfig(
    id="<YOUR_PROMPT_ID>",
    bindings={
        "user": {"source": "context.userId"},
        "session": {"source": "context.sessionId"},
        "job": {"source": "input"},
    },
)

Docker 명령 참조

uv run llamon run .              # 빌드 + 백그라운드 실행 (권장)
uv run llamon run . --no-detach  # foreground 실행
uv run llamon run . --down       # 컨테이너 종료
uv run llamon run . --dry-run    # 실행 예정 명령만 확인

# 로그 확인 (agent 컨테이너)
docker compose -f docker-compose.local.yml logs -f agent

v0.2.3 진단 코드 (Structured diagnostics)

v0.2.3부터 author-time validation 영역이 안정적인 진단 코드를 노출합니다. 자세한 family 표·payload 예시는 v0.2.3 변경사항 참조.

어디서 보이는지	어떻게 활용
`llamon doctor --output json`	`diagnostics[].code` 로 분류, `repair_id` 로 자동 수정 후보 매칭
`llamon graph inspect --output json`	`structure` + `diagnostics` + `summary.passed` 단일 응답 형식. CI에서는 이 값을 파싱하거나, exit-code 기반 검증이 필요하면 `llamon graph validate` 사용
Studio `/api/local-config` · `/api/local-skills` · `/api/node-ext-configs` GET	응답 body 의 `diagnostics: [...]` 키 — config.py 가 SyntaxError 일 때 `PRJ010`/`PRJ011`/`PRJ012` 가 file/line/col 과 함께 노출
Studio `/api/save` 409 응답	`detail.diagnostics: [...]` 에 `SAV001`/`SAV002` — `expected_sha` / `actual_sha` 비교 가능

분기/자동수정 가이드:

code 로 분류 (예: FLW006, PRJ010, SAV001).
repair_id 로 액션 선택 (예: bind-known-local-agent, fix-config-py-syntax, reload-or-force-save).
fix_safety: "safe" 만 자동 적용, "manual" 은 사용자 확인 후 적용.

폐쇄망 준비 오류

llamon prepare-offline / vendor-deps / package 단계에서 자주 만나는 오류입니다.

증상	원인	해결
`uv.lock`이 없습니다	lock 파일 미생성	`uv lock` 한 번 실행 후 다시 시도 (`prepare-offline`은 자동으로 시도)
`wheelhouse/` 가 비어있다고 doctor가 경고	다른 OS/ABI에서 수집된 wheel	`--clean` + `--python-platform`/`--python-version`/`--abi` 명시 후 재실행
`ResolutionImpossible` (uv)	의존성 충돌	`uv lock --upgrade` 또는 `pyproject.toml`에서 핀 완화
Docker 빌드 시 `sha256sum -c` 실패	SDK whl 교체 후 sha256 미갱신	`./update_sdk_wheel.sh .` 사용 (sha256 자동 갱신)
`package`가 `wheelhouse.sha256`을 못 찾음	`vendor-deps`를 건너뛰고 바로 `package` 실행	`prepare-offline`로 일괄 실행하거나 `vendor-deps`를 먼저 실행
폐쇄망에서 base image pull 실패	`Dockerfile`이 외부 registry 기본값 사용	`prepare-offline --python-base-image registry.internal/...` 또는 `restore-online` 후 재설정
온라인으로 되돌릴 때 Dockerfile 깨짐	직접 편집 후 충돌	`llamon restore-online .` 사용
폐쇄망 docker build 가 `uv pip install` 단계에서 `Could not find a version that satisfies <pkg>==<ver>`	개방망에서 PyPI 로 만든 `uv.lock` 의 정확 버전이 Nexus 미러에 sync 안 됨 (PyPI 릴리스 vs Nexus sync 갭)	v0.2.3+ patched Dockerfile 은 fallback 으로 Nexus 기준 `uv lock` 후 export/install 자동 재시도 (`# LLAMON: nexus-relock-fallback v1` marker). deterministic 빌드를 원하면 build 직전 `./deploy/relock-for-nexus.sh` 수동 실행

배포 단계 오류는 원격 배포의 마지막 섹션을 참조.

환경 설정 오류

`uv: command not found`

PATH가 올바르게 설정되지 않았습니다. 터미널을 재시작하거나 아래를 실행하세요:

macOS / Linux
Windows (PowerShell)

source $HOME/.local/bin/env

$env:PATH += ";$env:USERPROFILE\.local\bin"

`llamon: command not found` (uv run 없이 실행 시)

llamon-agent-template 디렉토리 안에서 uv run llamon으로 실행하거나, 전역 설치(uv tool install)를 먼저 진행하세요.

`uv sync --frozen` 실패 — whl 파일 없음

llamon-agent-template/ 디렉토리에 llamon_agent-*.whl과
llamon_agent-*.whl.sha256 파일이 모두 있어야 합니다.
파일이 없으면 제공받은 배포 패키지를 다시 확인하세요.

`OPENAI_API_KEY` 누락

OpenAI 템플릿(agent-openai, local OpenAI runtime)에서는 .env에 OPENAI_API_KEY가 필요합니다.

cp .env.example .env
# .env에 OPENAI_API_KEY=... 설정
uv run llamon run .