표현식과 디버깅

n8n의 표현식은 이중 중괄호 안에 $json.필드명 형태로 이전 노드의 데이터를 꺼내는 문법이며, 표현식 에디터의 드래그 기능과 Executions 탭의 실행 로그를 함께 쓰면 대부분의 오류를 빠르게 찾아 고칠 수 있습니다.

노드를 연결했는데 값이 안 넘어온다, 표현식 오류가 뜬다, 어제는 됐는데 오늘은 안 된다처럼 막히는 순간이 반드시 옵니다. 이 강의는 n8n에서 데이터를 꺼내는 표현식(Expression) 문법과, 뭔가 잘못됐을 때 원인을 찾는 디버깅 방법을 함께 다룹니다. 회로를 설계하는 것만큼, 테스터기로 어디가 끊겼는지 찾는 능력도 중요합니다.

표현식(Expression)이란?

n8n에서 노드의 입력 필드를 클릭하면 오른쪽에 Expression 탭이 보입니다. 이 탭으로 전환하면 고정 값 대신 이전 노드의 데이터를 동적으로 참조할 수 있습니다. 문법은 간단합니다. 이중 중괄호 {{ }} 안에 데이터 경로를 적으면 됩니다. 스프레드시트의 셀 참조(=B2+C2)와 비슷한 개념입니다.

자주 쓰는 표현식 패턴

{{ $json.name }}                        -- 현재 아이템의 name 필드
{{ $json["order-id"] }}                  -- 하이픈이 포함된 필드명 접근 시
{{ $json.user.email }}                  -- 중첩 객체 접근
{{ $json.items[0].price }}              -- 배열의 첫 번째 요소
{{ $input.first().json.total }}         -- 이전 노드 첫 아이템의 total
{{ $node["Gmail Trigger"].json.subject }} -- 특정 노드 이름으로 직접 접근
{{ $now.toISO() }}                      -- 현재 시각 (ISO 형식)
{{ $today.format("YYYY-MM-DD") }}       -- 오늘 날짜 포맷

$json과 주요 내장 변수

$json: 현재 아이템의 데이터 객체입니다. 노드 실행 결과의 Output 패널에서 보이는 것이 곧 $json의 내용입니다.
$input.all(): 이전 노드의 모든 아이템 목록을 배열로 반환합니다. 여러 항목을 한 번에 처리할 때 씁니다.
$input.first() / $input.last(): 이전 노드의 첫 번째/마지막 아이템을 반환합니다.
$node["노드이름"].json: 이름으로 특정 노드의 출력에 직접 접근합니다. 노드가 멀리 떨어져 있을 때 유용합니다.
$now: 현재 시각을 담은 Luxon DateTime 객체입니다. $now.minus({days: 7})처럼 날짜 계산이 가능합니다.
$vars.변수명: 워크플로우 설정에서 정의한 정적 변수에 접근합니다. API 엔드포인트처럼 반복 쓰는 값을 관리할 때 편리합니다.

표현식 에디터 100% 활용법

표현식을 직접 타이핑하지 않아도 됩니다. 노드를 한 번 실행한 뒤 표현식 에디터를 열면 왼쪽에 이전 노드의 데이터 트리가 보입니다. 원하는 필드를 오른쪽 입력창으로 드래그하면 표현식이 자동으로 완성됩니다. 에디터 하단 미리보기 창에서 실제 어떤 값이 들어오는지 즉시 확인할 수 있어, 오타나 경로 실수를 실행 전에 잡을 수 있습니다.

실행 로그로 원인 찾기

워크플로우 디버깅 절차

워크플로우 실행 후 왼쪽 상단의 Executions 탭으로 이동합니다.
실패한 실행을 클릭하면 어느 노드에서 멈췄는지 빨간색으로 표시됩니다.
실패한 노드를 클릭해 Input과 Output 패널을 각각 확인합니다. Input을 보면 어떤 데이터가 들어왔는지, Output의 Error 탭을 보면 왜 실패했는지 알 수 있습니다.
표현식 오류라면 해당 표현식을 에디터에서 열어 미리보기로 실제 값을 확인합니다.
문제가 된 노드 앞에 Edit Fields(Set) 노드를 임시로 끼워 넣어 데이터 형태를 출력해 보는 것도 빠른 방법입니다. 마치 회로 중간에 테스터기를 꽂는 것과 같습니다.

자주 나는 에러와 해결법

에러 메시지	원인	해결법
Cannot read properties of undefined	$json.name처럼 참조한 필드가 없거나 상위 객체가 undefined	Output 패널에서 실제 경로 확인 후 수정, 옵셔널 체이닝 $json.user?.email 사용
Expression Error: Unexpected token	표현식 문법 오류 (괄호 누락, 오타 등)	에디터 미리보기로 오류 위치 확인 후 드래그 방식으로 재입력
항상 null 또는 빈 값 반환	이전 노드가 실행되지 않았거나 데이터 경로가 틀림	이전 노드를 먼저 실행하고 Output 패널 확인
JSON parse error in AI response	AI가 지시한 JSON 형식을 어기고 텍스트를 섞어 반환	프롬프트에 JSON만 반환하도록 강화하고 structured output 옵션 활성화
Credential could not be decrypted	Credential이 삭제되었거나 암호화 키가 변경됨	해당 서비스 Credential을 다시 생성해 노드에 연결

복잡한 표현식을 만들기 전에 먼저 Edit Fields(Set) 노드에서 해당 표현식이 맞는 값을 반환하는지 테스트해 보세요. 테스트용 노드에서 검증 후 실제 노드로 복사하면, 실수를 줄이고 원인을 빠르게 좁힐 수 있습니다.

픽스드(Fixed) vs 표현식(Expression) 모드

n8n 노드의 모든 입력 필드는 두 가지 모드로 전환할 수 있습니다. 픽스드(Fixed) 모드는 항상 같은 고정 값을 씁니다. 표현식(Expression) 모드는 {{ }} 안에 경로를 넣어 실행 때마다 달라지는 동적 값을 씁니다. 필드 오른쪽의 작은 아이콘을 클릭하면 두 모드를 전환할 수 있습니다. '이 값이 매번 같나요?'라고 자문해 같으면 픽스드, 다르면 표현식을 고르세요.

표현식과 디버깅은 n8n에서 가장 많은 시간을 쓰는 부분이기도 하지만, 익숙해지면 어디서 막혔는지 1~2분 안에 찾을 수 있습니다. 데이터가 어디서 어떻게 흐르는지를 항상 Output 패널로 눈으로 확인하는 습관이 가장 빠른 지름길입니다. 에러가 나면 해당 노드의 Output JSON을 복사해 Claude나 ChatGPT에 붙여 넣으면 원인을 금방 찾아줍니다.