문제 해결

문제 해결 (Troubleshooting)

Docker Agent를 사용할 때 겪는 일반적인 문제와 해결 방법을 알려드릴게요.

출처: 문서

본문

일반적인 오류 (Common Errors)

컨텍스트 창 초과 (Context Window Exceeded)

에러 메시지: context_length_exceeded 또는 유사한 것.

  • TUI에서 /compact 를 사용해 대화 기록을 요약하고 줄이기
  • 에이전트 구성에서 num_history_items 를 설정해 모델로 보내는 메시지 수를 제한
  • 더 큰 컨텍스트를 가진 모델로 전환 (Claude Sonnet 4.5는 1M 토큰, Gemini는 최대 2M 지원)
  • 큰 작업을 더 작은 대화로 나누기

최대 반복 횟수 도달 (Max Iterations Reached)

에이전트가 작업을 완료하지 못한 채 max_iterations 한도에 도달했어요.

  • 에이전트 구성에서 max_iterations 를 늘리기 (기본값은 무제한이지만, 많은 에이전트가 20~50으로 설정)
  • 에이전트가 루프에 빠졌는지 확인 (--debug 를 켜서 도구 호출 확인)
  • 복잡한 작업을 더 작은 단계로 나누기

모델 폴백 발생 (Model Fallback Triggered)

기본 모델이 실패하면 Docker Agent는 자동으로 폴백 모델로 전환해요. "Switching to fallback model" 같은 로그 메시지를 찾아보세요.

  • 429 에러: Rate limiting(요청 제한) — 쿨다운 기간 동안 폴백을 계속 사용
  • 5xx 에러: 서버 문제 — 지수 백오프로 재시도한 뒤 폴백
  • 4xx 에러: 클라이언트 오류 — 바로 다음 모델로 건너뜀

에이전트 구성에서 폴백 동작을 구성해요:

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    fallback:
      models: [openai/gpt-5-mini, openai/gpt-4o-mini]
      retries: 2 # retries per model for 5xx errors
      cooldown: 1m # how long to stick with fallback after 429

자격 증명이나 모델 오류 누락 (Missing credentials or model errors)

Docker Agent가 시작 시 사용 가능한 모델을 찾지 못하면 실행 가능한 에러와 함께 빠르게 실패해요. 이 메시지는 정확한 다음 단계를 알려줘요. docker agent doctor 는 전체 그림을 볼 수 있는 가장 빠른 방법이에요 — 어떤 제공자에 자격 증명이 있는지, Docker Model Runner에 접근 가능한지, auto 가 어떤 모델을 선택할지 등을요.

필수 환경 변수가 설정되지 않음 (Required environment variables not set)

에이전트(또는 그것이 사용하는 도구)가 구성되지 않은 환경 변수에 의존하고 있어요:

The following environment variables must be set:
- ANTHROPIC_API_KEY

Provide them using any of these sources:
- Shell environment: export ANTHROPIC_API_KEY=<value>
- Env file: docker agent run --env-from-file <file> ...
- Docker Agent env file: docker agent setup (stores the key in ~/.config/cagent/.env)

See https://docs.docker.com/ai/docker-agent/guides/secrets/ for details.

나열된 시크릿 소스 중 아무거나 통해 변수를 설정해요. 누락된 변수가 모델 제공자 API 키일 때는, 에러에서 API 키가 필요 없는 로컬 모델(docker agent run --model dmr/ai/qwen3 ...)을 대신 실행하라고 제안하며 Set Up a Model 튜토리얼로 연결해줘요.

사용 가능한 모델 없음 (auto 선택 실패) — No model available (auto selection failed)

auto 모델 선택기가 구성된 클라우드 제공자도, 사용 가능한 Docker Model Runner 모델도 찾지 못했어요:

No model is currently available.

To fix this, you can:
- Pull a Docker Model Runner model, e.g. `docker model pull ai/qwen3`
- Install Docker Model Runner: https://docs.docker.com/ai/model-runner/get-started/
- Configure an API key for a cloud provider:
  - anthropic: ANTHROPIC_API_KEY
  - openai: OPENAI_API_KEY
...

클라우드 제공자 API 키를 구성하거나(아래 API keys not set 참고), 로컬 모델을 풀하면 돼요. Set Up a Model 튜토리얼이 두 경로를 모두 안내해요. docker agent doctor 를 실행하면 어떤 제공자에 자격 증명이 있고 Docker Model Runner에 접근 가능한지 확인할 수 있어요.

Docker Model Runner 모델이 풀되지 않음 (Docker Model Runner model not pulled)

dmr/... 모델을 요청했지만 로컬에 없어요:

model ai/qwen3 is not pulled in Docker Model Runner

To resolve this, you can:
- Pull it first: docker model pull ai/qwen3
- Or choose a model that is already available (see `docker model ls`).

대신 cannot query Docker Model Runner at <url> 이 보이면, Docker Model Runner가 설치되지 않았거나 실행 중이지 않은 거예요 — Model Runner get-started 가이드를 참고하세요.

Tip 실행 전에 진단하기 (Diagnose before you run) docker agent doctor (또는 docker agent doctor ./agent.yaml 로 파일의 요구 사항 포함)를 실행하면 세 가지 문제를 한 번에 확인해요. 실행을 막을 무언가가 있으면 0이 아닌 코드로 종료되어 CI 프리플라이트로 유용해요. CLI reference 참고.

디버그 모드 (Debug Mode)

어떤 문제든 첫 단계는 디버그 로깅을 켜는 거예요. 그러면 Docker Agent가 내부적으로 뭘 하는지 자세한 정보를 얻을 수 있어요.

# Enable debug logging (writes to ~/.cagent/cagent.debug.log)
$ docker agent run config.yaml --debug

# Write debug logs to a custom file
$ docker agent run config.yaml --debug --log-file ./debug.log

# Enable OpenTelemetry tracing for deeper analysis
$ docker agent run config.yaml --otel

Tip 이슈를 보고할 때는 항상 --debug 를 켜세요. 로그 파일에는 API 호출, 도구 실행, 에이전트 상호작용의 상세한 트레이스가 들어 있어요.

에이전트가 응답하지 않음 (Agent Not Responding)

API 키가 설정되지 않음 (API keys not set)

각 모델 제공자는 환경 변수로 자체 API 키를 요구해요:

Provider Environment Variable
OpenAI OPENAI_API_KEY
Anthropic ANTHROPIC_API_KEY
Google Gemini GOOGLE_API_KEY or GEMINI_API_KEY
Mistral MISTRAL_API_KEY
xAI XAI_API_KEY
Nebius NEBIUS_API_KEY
MiniMax MINIMAX_API_KEY
Requesty REQUESTY_API_KEY
OpenRouter OPENROUTER_API_KEY
GitHub Copilot GITHUB_TOKEN (copilot scope가 있는 PAT)
Azure OpenAI AZURE_API_KEY (token_key 로 재정의)
AWS Bedrock AWS_BEARER_TOKEN_BEDROCK 또는 AWS 자격 증명 체인 
# Verify your keys are set
$ env | grep API_KEY

잘못된 모델 이름 (Incorrect model name)

모델 이름은 제공자의 명명과 정확히 일치해야 해요. 흔한 실수:

  • 더 이상 사용되지 않는 모델 이름 사용 (예: gpt-4 대신 gpt-5-mini 나 gpt-4o)
  • 모델 참조는 대소문자를 구분해요: openai/gpt-5-mini ≠ openai/GPT-5-mini

네트워크 연결 (Network connectivity)

에이전트가 멈추거나 타임아웃되면 제공자의 API 엔드포인트에 도달할 수 있는지 확인해요. 방화벽, VPN, 프록시 설정이 요청을 차단할 수 있어요.

도구 실행 실패 (Tool Execution Failures)

MCP 도구를 찾지 못하거나 실패함 (MCP tools not found or failing)

  • MCP 도구 명령이 설치되어 있고 PATH에 있는지 확인
  • 파일 권한 확인 — 도구는 실행 가능해야 해요
  • Docker Agent와 통합하기 전에 MCP 도구를 독립적으로 테스트
  • Docker 기반 MCP 도구(ref: docker:*)는 Docker Desktop이 실행 중인지 확인

파일시스템 / 셸 도구 오류 (Filesystem / shell tool errors)

  • 에이전트에 올바른 toolset이 구성되어 있는지 확인 (type: filesystem, type: shell)
  • 작업 디렉터리가 존재하고 접근 가능한지 확인
  • macOS에서는 터미널에 필요한 권한(예: Full Disk Access)이 있는지 확인

도구 수명 주기 문제 (Tool lifecycle issues)

MCP와 LSP toolset은 슈퍼바이저가 관리하며, 크래시하거나 세션을 잃으면 자동으로 재시작해요. TUI는 그 슈퍼바이저를 두 개의 슬래시 명령으로 노출해요:

  • /tools — 통합된 도구 대화상자. 상단 섹션은 각 toolset을 현재 상태(Stopped, Starting, Ready, Degraded, Restarting, Failed), 재시작 횟수, 마지막 에러와 함께 나열하고, 하단 섹션은 에이전트가 호출할 수 있는 모든 도구를 나열해요. 도구가 없거나 멈춘 것처럼 보이면 여기부터 시작하세요.
  • /toolset-restart <name> — 이름 있는 toolset의 슈퍼바이저 주도 재연결을 강제해요. OAuth를 완료한 후, 원격 MCP 서버를 재배포한 후, 또는 gopls 같은 언어 서버가 응답하지 않을 때 유용해요.

401 invalid_token 을 반환하는 원격 MCP 서버(예: 저장된 OAuth 토큰이 취소되거나 회전된 경우)는 이제 자가 치유돼요: Docker Agent는 가능하면 조용히 refresh token을 새 것으로 교환하고, 불가능하면 다음 메시지에서 OAuth 재인증 프롬프트를 표시해요. 프로세스 재시작이 필요한 멈춘 toolset은 더 이상 없어요 — 단, 즉시 재인증하고 싶다면 /toolset-restart <name> 이 바로 강제해요.

stdio 전송을 사용하는 MCP 도구는 사용 가능해지기 전에 초기화 핸드셰이크를 완료해야 해요. 도구가 조용히 실패하면:

  • /tools 를 실행해 toolset이 Failed 이거나 Restarting 에 갇혀 있는지, 마지막 에러가 무엇인지 확인
  • --debug 를 켜고 로그에서 MCP 프로토콜 메시지 찾기
  • MCP 서버 프로세스가 시작되고 initialize 에 응답하는지 확인
  • 도구가 요구하는 환경 변수가 설정되어 있는지 확인 (env 와 env_file 을 toolset 구성에서 확인)

Note 시작 시 도구 목록 타임아웃 (Startup tool-listing timeout) 시작할 때 Docker Agent는 각 toolset에 도구 목록을 질의해요. toolset이 10초 내에 응답하지 않으면(예: tools/list 에 응답하지 않는 웨지된 MCP stdio 서버), 해당 toolset은 경고와 함께 건너뛰고 나머지 toolset은 정상적으로 로드돼요. 사이드바는 로드된 도구들을 보여주며 해결돼요 — 무한 스피너는 없어요. --debug 로 경고 메시지를 확인하고, 서버가 응답하게 되면 /toolset-restart <name> 을 사용하세요.

toolset이 빡빡한 루프에서 계속 크래시하면 toolset의 lifecycle 블록을 조정해요(예: backoff.initial 을 높이거나, max_restarts 를 낮추거나, best-effort 프로필로 전환) — 그래서 불안정한 의존성이 재시작 폭풍으로 증폭되지 않게 해요.

구성 오류 (Configuration Errors)

YAML 구문 문제 (YAML syntax issues)

Docker Agent는 시작 시 구성을 검증하고 줄 번호와 함께 에러를 보고해요. 흔한 문제:

  • 잘못된 들여쓰기 (YAML은 공백에 민감함)
  • 특수 문자(:, #, {, })를 포함한 값 주위에 따옴표 누락
  • 공백 대신 탭 사용

누락된 참조 (Missing references)

  • sub_agents 의 로컬 에이전트는 agents 섹션에 정의되어야 해요 (외부 OCI 참조인 myorg/agent:tag 는 레지스트리에서 자동으로 해석됨)
  • 이름 있는 모델 참조는 models 섹션에 존재해야 해요 (또는 openai/gpt-5 같은 인라인 형식 사용)
  • 에이전트가 참조하는 RAG 소스 이름은 rag 섹션에 정의되어야 해요

Toolset 검증 (Toolset validation)

  • path 필드는 memory와 tasks toolset, 그리고 에이전트 레벨 cache 블록에 유효해요
  • MCP toolset은 command(stdio), remote(Streamable HTTP/SSE), ref(Docker) 중 하나가 필요해요
  • 제공자 이름은 openai, anthropic, google, amazon-bedrock, dmr 등 중 하나여야 해요

Note 스키마 검증 (Schema Validation) 편집기에서 JSON 스키마를 사용하면 실시간 구성 검증과 자동 완성을 얻을 수 있어요.

세션 및 연결 문제 (Session & Connectivity Issues)

새 데이터베이스 에러로 다운그레이드 실패 (Downgrade fails with a newer-database error)

업그레이드 후 이전 Docker Agent 바이너리가 세션 데이터베이스를 열지 못하면, 데이터베이스에 이전 바이너리가 모르는 스키마 마이그레이션이 포함된 것일 수 있어요. 이전 버전이 만든 데이터베이스를 복원하거나, 마이그레이션을 포함한 바이너리를 사용하세요.

포트 충돌 (Port conflicts)

Docker Agent를 API 서버나 MCP 서버로 실행할 때 포트가 이미 사용 중이지 않은지 확인해요:

# Check if port 8080 is in use
$ lsof -i :8080

# Use a different port
$ docker agent serve api config.yaml --listen :9090

MCP 엔드포인트 접근성 (MCP endpoint accessibility)

원격 MCP 서버의 경우 엔드포인트에 도달 가능한지 확인해요:

# Test streamable HTTP endpoint
$ curl -v https://mcp-server.example.com/mcp

세션 격리 (Session isolation)

API 서버는 모든 대화를 SQLite 데이터베이스(session.db, 기본값)에 별개의 세션으로 저장해요. 각 세션은 UUID로 식별되며, 같은 세션 ID가 재사용될 때만 메시지가 섞여요. 대화가 서로 섞이는 것 같으면:

  • 각 클라이언트가 POST /api/sessions 로 새 세션을 만들도록 해요 (사용자 간에 세션 ID를 재사용하지 마세요).
  • --session-db 가 예상 경로를 가리키는지 확인 — 다른 실행의 오래된 데이터베이스가 이전 세션을 다시 드러낼 수 있어요.
  • GET /api/sessions/:id 로 실제 저장된 내용을 검사하고, 더 원하지 않는 세션은 DELETE /api/sessions/:id 로 지우세요.

HTTP 413: 요청 본문이 너무 큼 (HTTP 413: request body too large)

세 종류의 프로세스가 과도하게 큰 요청 본문을 413 Request Entity Too Large 로 거부해요: docker agent serve api, docker agent serve chat, 그리고 대화형 실행의 컨트롤 플레인(docker agent run --listen). 이들은 똑같이 구성되지 않아요: serve api 와 serve chat 는 각각 자체 --max-request-size 플래그(기본 1 MiB)를 노출해요. --listen 컨트롤 플레인에는 그런 플래그가 없어요 — 고정되고 구성할 수 없는 1 MiB 한도를 적용해요 — 그리고 --auth-token 도 없어요. 이 레이어들을 순서대로 살펴보세요:

  • 어떤 서버가 관여했는지 파악해요. serve api, serve chat, 그리고 연결된 실행의 --listen 컨트롤 플레인은 세 가지 별개의 프로세스 종류예요. serve api 와 serve chat 는 각각 자체 --max-request-size 플래그와 1 MiB 기본값을 가져요 — 413을 반환한 프로세스가 실제로 어떤 플래그로 시작됐는지 확인해요. --listen 컨트롤 플레인에는 --max-request-size 플래그가 없어요: 그 1 MiB 상한은 고정이에요.
  • 직렬화된 요청 본문을 측정해요, 소스 파일 크기가 아니라. JSON 문자열 이스케이프와 base64로 인코딩된 바이너리 콘텐츠의 base64 ~33% 확장은 둘 다 와이어 크기를 원래 파일 크기보다 훨씬 부풀려요 — 한도 바로 아래의 파일도 인코딩된 요청을 넘길 수 있어요.
  • 중간자를 배제해요. Docker Agent 앞에 역방향 프록시, 게이트웨이, 로드 밸런서가 있다면 보통 자체적이고 독립적인 본문 크기 한도를 적용하며(종종 다른 형식의 에러로), Docker Agent가 보기 전에 요청을 거부할 수 있어요.
  • 실제로 누가 에러를 반환했는지 확인해요. 413(또는 컨텍스트 길이 에러)은 요청이 도달한 뒤 모델 제공자 자체에서도 올 수 있어요; 그것은 --max-request-size 와 무관한 별개의 한도예요 — 위의 Context Window Exceeded 참고.
  • 해결해요. Docker Agent 자체 서버가 요청을 거부했음을 확인했다면, 콘텐츠를 덜 보내요 — 턴에 걸쳐 나누세요. serve api 나 serve chat 에서는 의도적으로 더 큰 --max-request-size 로 서버를 재시작할 수도 있어요(API Server 또는 Chat Server 참고). --listen 컨트롤 플레인에는 올릴 --max-request-size 플래그가 없어요 — 콘텐츠를 덜 보내는 것만이 해결책이에요.

사람들을 당황시키는 몇 가지:

  • --max-request-size 는 프로세스 시작 시 한 번 설정되고 그 서버가 처리하는 모든 요청에 적용돼요 — 요청별 또는 클라이언트별이 아니에요. 오직 serve api 와 serve chat 만 그것을 가지며, --listen 컨트롤 플레인의 1 MiB 상한은 바꿀 수 없어요.
  • 0 이나 음수 값은 1 MiB 기본값으로 폴백돼요; "제한 없음"을 뜻하지 않아요.
  • 같은 서버에 같은 과대 본문을 재시도해도 성공하지 않아요 — 요청 사이에 한도가 바뀌지 않아요.
  • 셋 모두에서 본문 크기 검사는 요청 인증보다 앞서 실행되므로, 과대 요청은 유효한 자격 증명 없이도 413로 돌아올 수 있어요.
  • 로컬 실행에 stdin을 파이프하는 것(docker agent run agent.yaml -)은 Docker Agent 자신의 인바운드 HTTP 경계를 넘지 않아요 — Docker Agent는 여전히 그 콘텐츠를 HTTP로 모델/제공자에게 보낼 수 있지만, --max-request-size 상한에 대해 측정될 Docker Agent 자신의 서버에 도달하는 요청은 없어요. 그러나 docker agent run --remote ... - 에 stdin을 파이프하는 것은 그 경계를 넘어요: CLI가 그 stdin 텍스트를 네이티브 API 실행 요청으로 직렬화하고, --remote 주소가 가리키는 Docker Agent 서버 — serve api 프로세스 또는 다른 실행의 --listen 컨트롤 플레인, 다른 프로토콜을 쓰는 serve chat 는 절대 아님 — 로 보내므로, 다른 요청처럼 그 서버 자체의 한도(serve api 는 구성 가능한 --max-request-size, --listen 컨트롤 플레인은 고정 1 MiB 상한)에 대해 측정돼요. 그 초기 요청은 메시지 텍스트만 실어요 — 현재 변환은 첫 메시지에 대해 로컬로 해결된 첨부 파일(@path, /attach, --attach)을 버리므로, 그것 단독으로는 413의 원인이 될 수 없어요. 하지만 --remote 실행이 전체 수명 동안 텍스트 전용으로 머무르지 않아요: 에이전트가 바쁜 동안 나중 메시지에 추가된 로컬로 해결된 첨부 파일 — 기본 steer 동작이나 명시적 후속 조치(Alt+Enter)를 통해 — 이 네이티브 API 요청의 일부로 전달되고, 같은 한도에 포함되며, 다른 과대 요청처럼 413을 유발할 수 있어요.

Warning --max-request-size 를 올리면 인증되지 않거나 악의적인 클라이언트가 서버가 요청당 버퍼링하도록 강제할 수 있는 메모리 양이 늘어나요. 배포의 노출 수준을 고려해 값을 선택하고, 루프백이 아닌 리스너에는 --auth-token(API 서버) 또는 --api-key / --api-key-env(챗 서버)를 짝지어주세요. --listen 컨트롤 플레인에는 두 플래그가 모두 없어요 — 다른 곳에서 접근 가능해야 한다면 루프백, 유닉스 소켓, 또는 인증하는 역방향 프록시 뒤에 유지하세요.

성능 문제 (Performance Issues)

높은 메모리 사용량 (High memory usage)

  • 큰 컨텍스트 창(64K+ 토큰)은 상당한 메모리를 소비해요 — max_tokens 를 줄이는 것을 고려
  • 에이전트 구성에서 num_history_items 를 사용해 대화 기록을 제한
  • DMR(로컬 모델)의 경우 하드웨어에 맞게 runtime_flags 를 조정 (예: GPU 레이어용 --ngl)

느린 응답 (Slow responses)

  • MCP 도구가 지연을 더하고 있는지 확인 (debug 로그에서 볼 수 있음)
  • TUI에서 /cost 명령을 사용해 토큰 사용량을 보고 비싼 상호작용을 파악
  • DMR의 경우 더 빠른 추론을 위해 추측 디코딩(speculative decoding) 활성화를 고려

도구 리소스 누수 (Tool resource leaks)

제대로 정리하지 않는 도구를 모니터링해요 — MCP 서버 시작/중지 수명 주기 이벤트에 대해 debug 로그를 확인하세요. 고아(orphan) 도구 프로세스가 시스템 리소스를 소비할 수 있어요.

에이전트 스토어 문제 (Agent Store Issues)

Pull / push 실패 (Pull / push failures)

# Test registry connectivity
$ docker pull docker.io/username/agent:latest

# Verify pulled agent content
$ docker agent share pull docker.io/username/agent:latest

에이전트 콘텐츠 문제 (Agent content issues)

  • 푸시된 YAML이 유효한지 확인 — 푸시 전에 로컬에서 docker agent run 실행
  • 참조된 리소스(MCP 도구, 파일)가 대상 머신에 있는지 확인
  • 자동 새로고침(--pull-interval)의 경우 서버에서 레지스트리에 접근 가능한지 확인

로그 분석 (Log Analysis)

debug 로그를 검토할 때 다음 키 패턴을 찾아보세요:

Log Pattern What It Indicates
"Starting runtime stream" 에이전트 실행 시작
"Tool call" 도구가 실행 중
"Tool call result" 도구 실행 완료
"Stream stopped" 에이전트 처리 완료
HTTP 429 Rate limiting — 폴백 모델 추가를 고려
context canceled 작업이 중단됨 (타임아웃 또는 사용자 취소)
[RAG Manager] RAG 검색 작업
[Reranker] 재랭킹 작업

Warning 여전히 막혔나요? 이 단계로도 해결되지 않으면 GitHub issue tracker에 debug 로그를 첨부해 버그를 등록하거나, Slack 에서 물어보세요.

더 알아보기 (Learn more)