Claude Code Bedrock cache_control scope 오류를 해결하는 3가지 방법: –resume 세션 복구 실패 완벽 해결 가이드

Claude Code를 사용하여 AWS Bedrock에 연결할 때 다음과 같은 오류 메시지가 나타난다면 당황하지 마세요.

InvokeModelWithResponseStream: operation error Bedrock Runtime:
InvokeModelWithResponseStream, https response error StatusCode: 400,
RequestID: 47574f13-c884-4b12-a003-6d0cf252d8dd,
ValidationException: system.1.cache_control.***.scope:
Extra inputs are not permitted

특히 --resume 명령어로 이전 세션을 복구할 때 자주 발생하는데, 이는 사용자의 설정 문제가 아니라 알려진 호환성 문제입니다.

근본 원인은 Claude Code가 Bedrock에서 지원하지 않는 scope 필드를 전송하기 때문입니다. 환경 변수 하나만 설정하면 30초 안에 해결할 수 있습니다.

핵심 가치: 이 글을 통해 오류의 원인을 파악하고, 3가지 해결 방안을 익히며, CLI, VS Code, JetBrains 등 다양한 환경에서 올바르게 설정하는 방법을 알아보세요.

Claude Code Bedrock 오류 원인 심층 분석

이 오류를 이해하려면 Anthropic 네이티브 API와 AWS Bedrock 간의 cache_control 지원 범위 차이를 알아야 합니다.

오류의 기술적 근본 원인

2026년 1월, Anthropic은 네이티브 API에 prompt-caching-scope-2026-01-05라는 베타 기능을 도입하며 cache_control 객체에 scope 필드를 추가했습니다.

{
  "cache_control": {
    "type": "ephemeral",
    "scope": "turn"
  }
}

Claude Code v2.1.24 버전부터는 이 scope 필드가 API 요청에 기본적으로 포함됩니다.

문제는 AWS Bedrock이 scope 필드를 인식하지 못한다는 점입니다. Bedrock의 스키마 검증은 매우 엄격하여, 알 수 없는 필드가 포함되면 즉시 400 오류를 반환합니다.

간단히 말해, Anthropic 네이티브 API는 유연하여 모르는 필드를 무시하지만, Bedrock은 엄격하게 거부합니다. Claude Code가 Bedrock이 모르는 필드를 보냈기 때문에 오류가 발생하는 것이죠.

🎯 기술적 조언: 이 문제는 AWS Bedrock을 통해 Claude를 호출하는 사용자에게만 영향을 미칩니다. APIYI(apiyi.com)와 같이 Anthropic 네이티브 API를 통해 접근하는 경우, 네이티브 API가 scope 필드를 완벽하게 지원하므로 오류가 전혀 발생하지 않습니다.

Claude Code –resume 사용 시 더 자주 발생하는 이유

이 오류가 --resume 전용은 아니지만, --resume으로 이전 세션을 복구할 때 훨씬 더 자주 발생합니다. 이유는 다음과 같습니다.

--resume의 내부 작동 메커니즘:

1. 이전 세션 로드: ~/.claude/projects/<프로젝트>/<세션ID>.jsonl에서 전체 대화 기록을 읽어옵니다.
2. 컨텍스트 재구성: 시스템 프롬프트, 도구 정의, 모든 이전 메시지를 전체 messages 배열로 다시 조립합니다.
3. 캐시 최적화: 복구된 컨텍스트는 일반적으로 크기 때문에(전체 대화 기록 포함), Claude Code는 비용 최적화를 위해 시스템 메시지에 cache_control 중단점을 더 적극적으로 설정합니다.
4. 요청 전송: 첫 번째 API 호출부터 전체 재구성된 컨텍스트 + cache_control(scope 필드 포함)이 포함됩니다.

핵심 포인트: 세션을 복구할 때 컨텍스트가 더 크기 때문에 → 캐시 최적화가 더 공격적으로 이루어지며 → cache_control 필드가 더 자주 등장하고 → 오류가 발생할 확률이 높아집니다.

새 세션을 시작할 때도 발생할 수 있지만, 초기 컨텍스트가 작아 캐시 마킹이 덜 밀집되므로 오류 발생 빈도가 낮습니다.

Claude Code Bedrock 오류 해결 방법 1: 실험적 Beta 기능 비활성화 (권장)

이 방법이 가장 추천하는 해결책입니다. 오류를 수정하면서도 기본적인 프롬프트 캐싱(Prompt Caching) 기능을 그대로 유지할 수 있기 때문이죠.

해결 원리

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1을 설정하면 Claude Code는 다음과 같이 동작합니다:

• 요청에서 Beta 헤더(예: prompt-caching-scope-2026-01-05)를 제거합니다.
• cache_control에서 scope 필드를 제거합니다.
• Bedrock이 지원하는 cache_control.type 및 cache_control.ttl과 같은 필드는 유지합니다.

즉, 새로운 scope 기능만 사용하지 않을 뿐, 프롬프트 캐싱을 통한 비용 절감 효과는 여전히 누릴 수 있습니다.

CLI 터미널 설정

macOS / Linux:

# 임시 설정 (현재 터미널 세션에서만 유효)
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

# 영구 설정 (shell 설정 파일에 추가)
echo 'export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1' >> ~/.zshrc
source ~/.zshrc

# bash를 사용하는 경우
echo 'export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1' >> ~/.bashrc
source ~/.bashrc

Windows (PowerShell):

# 임시 설정
$env:CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS = "1"

# 영구 설정
[System.Environment]::SetEnvironmentVariable("CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS", "1", "User")

설정 후, Claude Code를 바로 실행하면 됩니다:

# 새 세션 시작
claude

# 세션 복구 (이제 오류가 발생하지 않습니다)
claude --resume

VS Code 확장 프로그램 설정 (중요!)

VS Code 확장 프로그램은 shell 환경 변수를 읽지 않습니다. 따라서 .zshrc에 설정했더라도 VS Code 내의 Claude Code 확장 프로그램은 이를 인식하지 못합니다. 반드시 아래와 같이 설정해야 합니다.

방법 1: Claude 전역 설정 파일 수정 (권장)

~/.claude/settings.json 파일을 편집하세요:

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

방법 2: VS Code 설정 메뉴 이용

VS Code 설정 열기 → claude 검색 → 환경 변수 설정 항목 찾기 → CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 추가

JetBrains IDE 설정

JetBrains 계열 IDE(IntelliJ, WebStorm, PyCharm 등)의 Claude Code 플러그인도 별도로 구성해야 합니다:

~/.claude/settings.json 파일을 편집하세요 (VS Code와 동일한 파일 사용):

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

💡 꿀팁: ~/.claude/settings.json은 Claude Code의 전역 설정 파일로, 모든 클라이언트(CLI, VS Code, JetBrains)가 이 파일을 참조합니다. 여기서 환경 변수를 설정하는 것이 가장 간편하며, 한 번의 설정으로 모든 플랫폼에 적용됩니다.

Claude Code Bedrock 오류 해결 방법 2: 프롬프트 캐싱 비활성화

방법 1로도 문제가 해결되지 않는 아주 드문 경우에는 프롬프트 캐싱을 완전히 비활성화할 수 있습니다.

해결 원리

DISABLE_PROMPT_CACHING=1을 설정하면 Claude Code는 요청에서 모든 cache_control 필드를 제거합니다. cache_control이 없으면 당연히 scope도 없으므로 오류가 완전히 사라집니다.

단점: 프롬프트 캐싱으로 인한 비용 절감 효과가 사라집니다. 긴 대화 시나리오에서는 토큰 비용이 더 많이 발생할 수 있습니다.

설정 방법

# CLI
export DISABLE_PROMPT_CACHING=1

# ~/.claude/settings.json (모든 플랫폼 공통)
{
  "env": {
    "DISABLE_PROMPT_CACHING": "1"
  }
}

어떤 방법을 선택해야 할까요?

Claude Code Bedrock 오류 해결 방안 3: 이중 안전장치 설정

두 가지 환경 변수를 동시에 설정하여 Bedrock에서 지원하지 않는 모든 필드가 확실하게 제거되도록 합니다.

# CLI
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export DISABLE_PROMPT_CACHING=1

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "DISABLE_PROMPT_CACHING": "1"
  }
}

이 설정은 가장 안전한 방법으로, 운영 환경에서 절대적인 안정성이 필요한 경우에 권장합니다.

🚀 또 다른 방법: 환경 변수를 설정하는 것이 번거롭거나 Bedrock의 호환성 문제에서 벗어나고 싶다면, Anthropic 네이티브 API로 전환하는 것을 고려해 보세요. APIYI(apiyi.com) 플랫폼을 통해 Anthropic 네이티브 인터페이스에 직접 접속하면 scope를 포함한 모든 프롬프트 캐싱 기능을 완벽하게 지원하며, AWS 계정 없이도 이용할 수 있습니다.

Claude Code Bedrock 오류 해결을 위한 전체 점검 절차

어떤 해결책이 본인에게 적합한지 확실하지 않다면, 다음 절차에 따라 점검해 보세요.

1단계: 오류 유형 확인

오류 메시지에 다음 키워드가 포함되어 있는지 확인하세요:

cache_control.***.scope: Extra inputs are not permitted

또는

ValidationException: ... cache_control ... scope

이 메시지가 있다면 scope 필드 호환성 문제입니다.

2단계: 호출 경로 확인

# 현재 Claude Code가 사용하는 API 엔드포인트 확인
echo $ANTHROPIC_BASE_URL
echo $CLAUDE_CODE_USE_BEDROCK

CLAUDE_CODE_USE_BEDROCK=1 또는 AWS_REGION 등 Bedrock 관련 변수가 설정되어 있다면 Bedrock을 사용 중인 것입니다.

3단계: 해결책 적용

# 먼저 방안 1 시도
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

# 해결 여부 테스트
claude --resume

4단계: 해결 여부 검증

# 환경 변수 적용 확인
echo $CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS
# 결과: 1 출력 확인

# 새 세션 테스트
claude

# 세션 복구 테스트
claude --resume

5단계: 여전히 오류가 발생하는 경우

# 방안 2 추가
export DISABLE_PROMPT_CACHING=1

# settings.json 확인
cat ~/.claude/settings.json

settings.json 형식이 올바른지 확인하세요:

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "DISABLE_PROMPT_CACHING": "1"
  }
}

🎯 기술 제언: LiteLLM과 같은 게이트웨이 프록시를 통해 Bedrock에 연결하는 경우, LiteLLM은 2026년 3월부터 scope 필드를 자동으로 제거하는 기능을 내장하고 있습니다(PR #22867). 최신 버전의 LiteLLM으로 업데이트하면 이 문제를 해결할 수 있습니다. 더 안정적인 Claude API 연결 방식을 찾으신다면, APIYI(apiyi.com)에서 제공하는 Anthropic 네이티브 API 채널을 이용해 보세요. 이러한 호환성 제한 없이 자유롭게 사용할 수 있습니다.

Claude Code Bedrock 기타 일반적인 호환성 문제

cache_control.scope만이 Bedrock의 유일한 호환성 걸림돌은 아닙니다. Bedrock 사용자가 흔히 겪는 유사한 문제들은 다음과 같습니다.

대부분의 문제는 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 설정으로 한 번에 해결할 수 있습니다. 지원되지 않는 이러한 필드들은 본질적으로 Anthropic 네이티브 API의 베타 기능이기 때문입니다.

💰 비용 최적화: Bedrock의 프롬프트 캐싱은 5분과 1시간 TTL만 지원합니다. 캐싱 의존도가 높은 환경이라면 APIYI(apiyi.com)를 통해 Anthropic 네이티브 API를 연동하여 더 유연한 캐싱 전략을 활용하고, 위와 같은 호환성 문제로 인한 트러블슈팅 비용을 절감해 보세요.

Claude Code Bedrock 오류 관련 FAQ

{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

Claude Code Bedrock 오류 해결을 위한 빠른 참조표

요약

Claude Code를 AWS Bedrock을 통해 호출할 때 발생하는 cache_control.scope: Extra inputs are not permitted 오류는 Bedrock이 Anthropic 네이티브 API의 scope 베타 필드를 지원하지 않기 때문에 발생합니다.

가장 빠른 해결 방법:

# CLI에서 실행
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

// ~/.claude/settings.json 설정 (권장, 모든 플랫폼 공통)
{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

꼭 기억해야 할 세 가지 포인트:

1. 사용자의 잘못이 아닙니다 — Bedrock과 Anthropic API 간의 기능 차이로 인해 발생하는 문제입니다.
2. VS Code 사용자는 settings.json에 설정해야 합니다 — 셸 환경 변수는 VS Code 확장 프로그램에서 읽어오지 못합니다.
3. --resume가 근본 원인은 아닙니다 — 모든 Bedrock 호출에서 발생할 수 있으며, --resume 사용 시 더 쉽게 노출될 뿐입니다.

Bedrock 호환성 문제로 고민하고 싶지 않다면, Anthropic 네이티브 API로 전환하는 것이 근본적인 해결책입니다. APIYI(apiyi.com)를 통해 네이티브 Claude API에 빠르게 연결하면 별도의 AWS 인프라 없이도 모든 기능을 완벽하게 지원받을 수 있습니다.

작성자: APIYI 기술팀
기술 교류: APIYI(apiyi.com)를 방문하여 더 많은 Claude Code 사용 튜토리얼과 기술 지원을 확인하세요.
업데이트 날짜: 2026년 4월
적용 버전: Claude Code v2.1.24 이상, AWS Bedrock

참고 자료:

1. GitHub Issue #23220: Claude Code v2.1.24+ cache_control.scope 오류
   • 링크: github.com/anthropics/claude-code/issues/23220
2. GitHub Issue #41731: VS Code 확장 프로그램의 지원되지 않는 scope 필드 전송 문제
   • 링크: github.com/anthropics/claude-code/issues/41731
3. AWS Bedrock 프롬프트 캐싱 문서:
   • 링크: docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html
4. Anthropic 프롬프트 캐싱 문서:
   • 링크: docs.anthropic.com/en/docs/build-with-claude/prompt-caching
5. Amazon Bedrock 기반 Claude Code 공식 문서:
   • 링크: docs.anthropic.com/en/docs/claude-code/bedrock