Google Apps Script Cannot read properties of null 해결: 구글시트 getRange 오류 원인과 처리법

Google Apps Script에서 Cannot read properties of null 오류가 나오면, 대부분 시트, 스프레드시트, 범위 객체가 비어 있는데 그 뒤에 getRange() 같은 메서드를 호출했기 때문입니다. 먼저 시트 이름 오타, getSheetByName() 결과, getActiveSpreadsheet() 실행 환경, 트리거 실행 방식을 차례대로 점검합니다.

오류가 난 줄만 보면 getRange()가 문제처럼 보이지만, 실제 원인은 그 앞에서 만든 sheet 객체가 null인 경우가 많습니다. 초보자는 오류 줄 번호와 함께, 그 줄 바로 앞에서 만든 객체가 정상적으로 만들어졌는지 확인하는 방식으로 접근하면 됩니다.

Google Apps Script에서 null 객체를 확인한 뒤 getRange 오류를 해결하는 흐름입니다.

📑 목차 [보기]

• Cannot read properties of null 오류는 왜 나올까
• 가장 먼저 확인할 것
• 원인 1. 시트 이름이 정확하지 않다
• 원인 2. getActiveSpreadsheet가 null을 반환한다
• 원인 3. openById에 넣은 스프레드시트 ID가 잘못됐다
• 원인 4. 트리거 실행 환경이 수동 실행과 다르다
• 빠른 확인용 디버깅 코드
• 안전하게 수정한 예시 코드
• 재발 방지 체크리스트
• 공식 문서로 더 확인하기
• 함께 보면 좋은 글
• FAQ

Cannot read properties of null 오류는 왜 나올까

대표적인 오류 메시지는 아래와 같습니다.

TypeError: Cannot read properties of null (reading 'getRange')

이 문장은 null인 객체에서 getRange()를 읽으려 했다는 뜻입니다. 쉽게 말해, 시트를 찾지 못했는데 그 시트에서 범위를 가져오려고 한 상황입니다.

비슷한 오류로는 아래 메시지도 자주 나옵니다.

TypeError: Cannot read properties of null (reading 'getDataRange')
TypeError: Cannot read properties of null (reading 'getSheetByName')
TypeError: Cannot read properties of null (reading 'getValues')

null은 값이 비어 있다는 뜻에 가깝습니다. Google Apps Script에서는 시트 이름을 잘못 입력했거나, 현재 실행 환경에서 활성 스프레드시트를 찾지 못했거나, 잘못된 파일 ID를 사용했을 때 이런 상황이 생길 수 있습니다.

가장 먼저 확인할 것

오류를 해결할 때는 코드 전체를 처음부터 고치기보다, 어떤 객체가 null인지 먼저 찾는 것이 빠릅니다. 특히 reading 'getRange'라고 나오면 getRange() 앞에 있는 객체를 확인해야 합니다.

확인 위치	의심할 원인	확인 방법
sheet.getRange()	시트를 찾지 못함	Logger.log(sheet)
ss.getSheetByName()	스프레드시트 객체가 없음	Logger.log(ss)
트리거 실행	활성 파일 환경이 다름	openById() 검토

원인 1. 시트 이름이 정확하지 않다

가장 흔한 원인은 getSheetByName()에 넣은 시트 이름이 실제 구글시트 탭 이름과 다른 경우입니다. 예를 들어 코드에는 Data라고 적었지만 실제 탭 이름이 data, Data , 데이터라면 시트를 찾지 못할 수 있습니다.

아래 코드는 겉으로는 문제가 없어 보이지만, Data라는 이름의 시트가 없으면 sheet가 null이 됩니다. 그 상태에서 sheet.getRange()를 실행하면 오류가 납니다.

function readSheet() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName('Data');
  const values = sheet.getRange('A1:C10').getValues();
  Logger.log(values);
}

시트 이름은 실제 탭 이름과 완전히 같아야 합니다. 앞뒤 공백, 한글·영문 오타, 대소문자, 괄호, 숫자까지 그대로 비교해야 합니다.

원인 2. getActiveSpreadsheet가 null을 반환한다

SpreadsheetApp.getActiveSpreadsheet()는 현재 활성화된 스프레드시트를 가져올 때 사용합니다. 구글시트에 연결된 컨테이너 바인딩 스크립트에서는 자연스럽게 작동하는 경우가 많지만, 독립 실행형 스크립트나 일부 트리거 실행 환경에서는 기대한 파일을 찾지 못할 수 있습니다.

이때는 ss 자체가 null인지 먼저 확인합니다. ss가 비어 있는데 그 뒤에 ss.getSheetByName()을 호출하면 다른 형태의 Cannot read properties of null 오류가 날 수 있습니다.

function checkSpreadsheet() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  Logger.log(ss);

  if (!ss) {
    throw new Error('활성 스프레드시트를 찾을 수 없습니다. 스크립트 실행 위치를 확인하세요.');
  }
}

원인 3. openById에 넣은 스프레드시트 ID가 잘못됐다

SpreadsheetApp.openById()는 스프레드시트 파일 ID로 특정 파일을 직접 여는 방식입니다. 시간 기반 트리거나 독립 실행형 스크립트처럼 활성 스프레드시트가 애매한 환경에서는 이 방식이 더 안전할 수 있습니다.

다만 ID를 잘못 넣거나, 실행 계정에 해당 파일 접근 권한이 없으면 정상적으로 파일을 열 수 없습니다. 스프레드시트 ID는 구글시트 주소에서 /d/와 /edit 사이에 있는 긴 문자열입니다.

function readSheetById() {
  const spreadsheetId = '스프레드시트_ID를_여기에_입력';
  const ss = SpreadsheetApp.openById(spreadsheetId);
  const sheet = ss.getSheetByName('Data');

  if (!sheet) {
    throw new Error('Data 시트를 찾을 수 없습니다.');
  }

  const values = sheet.getDataRange().getValues();
  Logger.log(values);
}

openById()를 쓸 때도 시트 이름 확인은 필요합니다. 파일은 열렸지만 그 안에 Data 시트가 없으면 sheet는 여전히 null이 될 수 있습니다.

원인 4. 트리거 실행 환경이 수동 실행과 다르다

수동 실행은 잘 되는데 시간 기반 트리거에서만 오류가 난다면 실행 환경 차이를 의심해야 합니다. 수동 실행은 사용자가 편집기에서 직접 실행하지만, 트리거는 정해진 조건이나 시간에 자동으로 실행됩니다.

이 경우 활성 스프레드시트에 기대는 코드보다 파일 ID로 여는 코드가 더 안정적일 수 있습니다. 특히 매일 오전에 자동으로 데이터를 읽는 스크립트라면 getActiveSpreadsheet() 대신 openById()를 검토합니다.

트리거 자체의 권한, 실행 계정, 시간 기반 실행 문제까지 함께 의심된다면 아래 관련 글을 함께 확인할 수 있습니다.

빠른 확인용 디버깅 코드

아래 코드는 ss와 sheet가 정상적으로 만들어졌는지 확인하는 용도입니다. 오류가 난 코드를 바로 고치기 전에 먼저 실행해 보면 원인을 좁히기 쉽습니다.

function checkSheet() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  Logger.log(ss);

  const sheet = ss.getSheetByName('Data');
  Logger.log(sheet);

  if (!sheet) {
    throw new Error('Data 시트를 찾을 수 없습니다. 시트 이름을 확인하세요.');
  }
}

Logger.log(ss) 결과가 비어 있으면 스프레드시트 객체부터 확인해야 합니다. Logger.log(sheet) 결과가 비어 있으면 시트 이름이나 시트 존재 여부를 확인해야 합니다.

안전하게 수정한 예시 코드

실제 자동화 코드에서는 객체를 사용하기 전에 먼저 확인하는 습관이 좋습니다. 아래처럼 if (!ss), if (!sheet)를 넣으면 오류 원인을 더 쉽게 알 수 있습니다.

function readSheetSafely() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();

  if (!ss) {
    throw new Error('활성 스프레드시트를 찾을 수 없습니다. 스크립트 실행 위치를 확인하세요.');
  }

  const sheet = ss.getSheetByName('Data');

  if (!sheet) {
    throw new Error('Data 시트를 찾을 수 없습니다. 시트 이름, 공백, 대소문자를 확인하세요.');
  }

  const values = sheet.getRange('A1:C10').getValues();
  Logger.log(values);
}

이렇게 수정하면 단순히 Cannot read properties of null만 보는 것이 아니라, 어떤 단계에서 실패했는지 직접 만든 오류 메시지로 확인할 수 있습니다.

재발 방지 체크리스트

같은 오류가 반복된다면 아래 순서대로 점검합니다. 특히 시트 이름을 바꾼 뒤 자동화가 갑자기 실패했다면 4번과 5번을 먼저 봅니다.

공식 문서로 더 확인하기

Google Apps Script의 스프레드시트 객체, 시트 객체, 트리거 실행 방식은 공식 문서에서 기준을 확인하는 것이 가장 안전합니다. 메서드 이름과 반환 객체를 확인하면서 현재 코드의 어느 단계에서 null이 생기는지 점검합니다.

함께 보면 좋은 글

FAQ

Google Apps Script의 Cannot read properties of null 오류는 getRange 줄만 고치기보다, 그 앞에서 만든 스프레드시트와 시트 객체가 실제로 존재하는지 확인하는 것이 핵심입니다.