beautifulsoups.dev
Published on

Arrow Invalid - offset overflow 에러 원인·해결

Authors

서버 로그나 배치 파이프라인에서 ArrowInvalid: offset overflow 혹은 Invalid: offset overflow가 터지면, 대개 데이터 자체가 깨졌다기보다 Arrow의 가변 길이 타입이 내부적으로 사용하는 오프셋(offset) 배열이 표현 가능한 범위를 넘은 상황입니다. 특히 Parquet read_table 또는 Spark toPandas()/collect() 같은 경로에서 Arrow가 켜져 있을 때 자주 보입니다.

이 글에서는 오프셋이 무엇인지부터, 어떤 데이터/연산이 오버플로를 유발하는지, 그리고 환경별로 실전에서 바로 적용 가능한 해결책을 정리합니다.

에러가 의미하는 것: Arrow의 오프셋 모델

Arrow의 string, binary, list 같은 가변 길이(Variable-length) 컬럼은 내부적으로 아래 두 덩어리로 저장됩니다.

  • 값이 이어 붙은 values 버퍼
  • 각 행의 시작 위치를 가리키는 offsets 배열

예를 들어 문자열 배열이라면 offsets[i]와 offsets[i+1] 사이가 i번째 문자열의 바이트 구간입니다.

문제는 많은 구현에서 기본 오프셋이 32비트 정수(int32) 인 경우가 많다는 점입니다. 그러면 values 버퍼의 총 길이(바이트)가 커질 때, 오프셋이 2^31-1(약 2GB) 근처를 넘으며 오버플로가 발생할 수 있습니다.

정리하면 이 에러는 보통 다음 중 하나입니다.

  1. 하나의 컬럼(혹은 하나의 청크)의 가변 길이 데이터가 너무 커서 int32 오프셋 범위를 초과
  2. 연산 과정에서 여러 배치를 합치며 단일 배열로 연결(concatenate) 되어 2GB 장벽을 넘음
  3. 잘못된 타입 캐스팅/스키마 추론으로 large_* 타입이 아닌 일반 타입으로 강제되어 오프셋 폭이 좁아짐

대표 원인 6가지

1) 초대형 문자열/바이너리 컬럼(로그, HTML, JSON blob)

예: 한 행이 수 MB인 JSON 문자열이 수십만 행 쌓이면, 한 배치에서만 2GB를 쉽게 넘습니다.

  • string/binary는 보통 int32 offset
  • 해결: large_string/large_binary 또는 배치 분할

2) list/array 컬럼 폭발(explode 반대 방향)

리스트 컬럼이 있고, 조인/집계 과정에서 리스트가 더 커지는 패턴이면 list의 offsets도 같은 문제를 겪습니다.

  • 해결: large_list로 승격 또는 리스트를 정규화(행으로 풀기)

3) Parquet row group / Arrow batch 크기 과대

파일 자체는 여러 row group으로 나뉘어도, 읽는 쪽에서 큰 배치로 합치면 위험합니다.

  • 해결: batch_size를 낮추거나 row group 단위로 처리

4) Spark에서 Arrow 기반 toPandas() 사용

Spark는 spark.sql.execution.arrow.pyspark.enabled=true일 때 Arrow로 컬럼을 넘기는데, 이때 대형 문자열 컬럼이 있으면 오프셋 오버플로가 터질 수 있습니다.

  • 해결: Arrow 비활성화, 대상 컬럼 제외, 샘플링, 파티션/배치 분할

5) Pandas string dtype와의 상호 변환

Pandas의 object/string[python]/string[pyarrow] 변환 과정에서 Arrow 배열로 재구성되며 큰 단일 배열이 생길 수 있습니다.

  • 해결: 변환 전에 컬럼 잘라내기, pyarrow의 large_* 타입 사용

6) 스키마 불일치로 large_*가 string으로 다운캐스팅

어딘가에서 스키마를 명시하지 않거나, 다른 파일들과 병합하면서 large_string이 string으로 강제될 수 있습니다.

  • 해결: 읽기/쓰기 시 스키마 고정, 병합 전에 타입 점검

빠른 진단 체크리스트

아래 질문에 Yes가 하나라도 있으면 오프셋 오버플로 가능성이 큽니다.

  • 특정 컬럼이 string/binary/list 계열인가?
  • 해당 컬럼의 평균 길이 또는 최대 길이가 큰가? (예: 긴 JSON, base64, HTML)
  • concat, groupby 후 list로 모으기, join으로 중복이 늘어나는 연산이 있는가?
  • Parquet를 한 번에 크게 읽거나, Spark에서 toPandas()로 한 방에 가져오나?

Python(PyArrow)에서 재현과 해결

재현 예시: 큰 문자열을 한 배열로 만들기

아래 코드는 환경에 따라 메모리 부담이 크니 주의하세요. 핵심은 string 오프셋이 int32라 2GB 근처에서 문제가 난다는 점입니다.

import pyarrow as pa

# 큰 문자열을 반복해 values 버퍼를 키움
s = "x" * (10 * 1024 * 1024)  # 10MB
arr = pa.array([s] * 300, type=pa.string())  # 대략 3GB 수준을 유도

환경에 따라 생성 중에 바로 예외가 나거나, 후속 연산(예: pa.Table.from_arrays)에서 터질 수 있습니다.

해결 1) large_string/large_binary로 승격

Arrow에는 64비트 오프셋을 쓰는 large_* 타입이 있습니다.

import pyarrow as pa

s = "x" * (10 * 1024 * 1024)
arr = pa.array([s] * 300, type=pa.large_string())

tbl = pa.Table.from_arrays([arr], names=["payload"])

데이터 레이크/교환 포맷에서 large_*가 항상 호환되는 건 아니므로, 소비자(예: Spark, Athena, 다른 언어 바인딩)가 지원하는지 확인해야 합니다.

해결 2) 배치/청크를 쪼개서 처리

대부분의 경우는 한 번에 단일 Arrow 배열로 만들지 않는 것이 가장 현실적입니다.

import pyarrow as pa

def chunked_table(strings, chunk_size=10_000):
    batches = []
    for i in range(0, len(strings), chunk_size):
        arr = pa.array(strings[i:i+chunk_size], type=pa.string())
        batches.append(pa.RecordBatch.from_arrays([arr], ["payload"]))
    return pa.Table.from_batches(batches)

해결 3) Parquet 읽기에서 배치 크기 제한

pyarrow.parquet.ParquetFile.iter_batches를 쓰면 배치 단위로 안전하게 처리할 수 있습니다.

import pyarrow.parquet as pq

pf = pq.ParquetFile("data.parquet")
for batch in pf.iter_batches(batch_size=2048):
    # batch는 RecordBatch
    # 여기서 필요한 컬럼만 처리/필터링 후 다음으로 넘김
    pass

해결 4) 문제 컬럼을 제외하거나 길이를 제한

현업에서 가장 흔한 처방입니다. 예를 들어 디버그용 payload를 제거하거나, 길이를 잘라냅니다.

import pyarrow.compute as pc

# tbl: pa.Table
trimmed = tbl.set_column(
    tbl.schema.get_field_index("payload"),
    "payload",
    pc.utf8_slice_codeunits(tbl["payload"], start=0, stop=10_000)
)

Spark(PySpark)에서의 해결

Spark에서 이 에러가 보이면, 대개 Arrow 최적화 경로에서 발생합니다.

1) toPandas() 전에 컬럼/행 줄이기

# 필요한 컬럼만 선택
small_df = df.select("id", "created_at")

# 또는 샘플링/필터링
small_df = df.where("dt >= '2026-02-01'").limit(100000)

pdf = small_df.toPandas()

2) Arrow 비활성화(우회)

성능은 떨어질 수 있지만, 장애 회피가 목적이면 가장 빠릅니다.

spark.conf.set("spark.sql.execution.arrow.pyspark.enabled", "false")
pdf = df.toPandas()

3) 파티션 단위로 나눠 Pandas로 변환

한 번에 전량을 가져오지 말고, 파티션/윈도우로 분리합니다.

from pyspark.sql import functions as F

# 날짜 단위로 쪼개기 예시
for row in df.select("dt").distinct().collect():
    dt = row["dt"]
    part = df.where(F.col("dt") == dt).select("id", "payload")
    # 필요하면 payload 제외
    pdf = part.select("id").toPandas()

Rust / Java 등 다른 언어에서도 통하는 원칙

언어가 달라도 해결 방향은 동일합니다.

  • Utf8/Binary 대신 LargeUtf8/LargeBinary(또는 이에 준하는 64-bit offset 타입) 사용
  • 큰 컬럼은 스트리밍/배치 처리
  • 조인/집계로 데이터가 폭증하는 지점에서 크기 상한을 두기

예: Rust arrow 크레이트 계열에서는 LargeStringArray 같은 타입을 검토합니다(버전별 네이밍 차이 가능).

“왜 갑자기” 터지나: 데이터 분포 변화가 트리거

이 에러는 코드 변경 없이도 갑자기 발생할 수 있습니다.

  • 특정 날짜에만 payload가 비정상적으로 커짐(배포 로그, 에러 스택트레이스 폭증)
  • 조인 키 품질 저하로 카디널리티가 무너져 중복이 폭발
  • 압축률 좋은 텍스트가 대량 유입되어 파일 크기는 작아 보이지만, 디코딩 후 메모리 상에서는 거대해짐

따라서 단순히 “메모리 늘리기”로는 해결이 안 되는 경우가 많고, 가변 길이 컬럼의 총 바이트 수를 제어해야 합니다.

운영 환경에서의 권장 대응 순서

  1. 문제 컬럼 찾기: 에러 직전 작업에서 string/binary/list 컬럼을 우선 의심
  2. 해당 컬럼 통계 확인: 최대 길이, 상위 1% 길이, 전체 바이트 추정
  3. 즉시 완화: 컬럼 제외, 길이 제한, 샘플링, 배치 크기 축소
  4. 근본 해결: large_* 타입 도입 또는 스키마 고정, 파이프라인을 스트리밍 처리로 전환
  5. 재발 방지: 데이터 품질 체크(행 길이 상한), 조인 폭발 감지(카디널리티 가드)

자주 묻는 질문

Q1. large_string으로 바꾸면 무조건 해결되나?

오프셋 오버플로 자체는 완화되지만, 결국 메모리/네트워크 전송량 문제가 남습니다. large_*는 “표현 가능”하게 만들 뿐, 대형 payload를 한 번에 옮기는 설계를 정당화하진 않습니다.

Q2. Parquet 파일이 수백 MB인데 왜 2GB 오버플로가 나나?

압축된 파일 크기와, Arrow가 메모리에 펼친 values 버퍼 크기는 다릅니다. 특히 긴 텍스트가 반복되면 압축률이 좋아 파일은 작아도, 디코딩 후에는 매우 커질 수 있습니다.

Q3. Kubernetes/EKS에서만 더 잘 터지는 느낌인데?

컨테이너 메모리 제한 때문에 OOM이 먼저 날 것 같지만, 이 에러는 OOM 이전에 타입/오프셋 범위 검사에서 먼저 실패할 수 있습니다. 또한 워커 수/파티션 수 변화로 “한 태스크가 처리하는 배치 크기”가 커지면 재현이 쉬워집니다. 대규모 배치 장애를 다루는 관점은 EKS Pod Pending - CNI IP 고갈 해결법처럼 원인 분해와 빠른 완화책을 함께 준비하는 방식이 유효합니다.

결론

Arrow Invalid: offset overflow는 Arrow의 가변 길이 컬럼이 내부적으로 사용하는 오프셋 폭(주로 32비트)과, 실제 데이터의 총 바이트 규모가 충돌할 때 발생합니다. 해결의 핵심은 다음 두 가지입니다.

  • 표현 폭을 늘리기: large_string, large_binary, large_list
  • 한 번에 합치지 않기: 배치/청크 처리, 컬럼 제외, 길이 제한

파이프라인에서 “긴 문자열/리스트를 대량으로 한 번에 옮기는” 경로를 찾고, 그 구간을 스트리밍/분할 처리로 바꾸면 재발 가능성을 크게 줄일 수 있습니다.

추가로, 장애 원인 추적과 재시도/완화 패턴을 함께 정리해두면 운영 비용이 줄어듭니다. 예를 들어 외부 API 호출이 섞인 파이프라인이라면 OpenAI 429·5xx 재시도, Idempotency 키로 중복 결제 막기처럼 실패 시나리오를 체계화하는 접근이 도움이 됩니다.

Discuss on Twitter • View on GitHub