발행일: 2026-10-06(화) 11:44
홈›도서›하루 30분 n8n ③›부록 C
부록난이도 ★☆☆
부록 C

자주 발생하는 오류와 해결법

📖 이 DAY는 개념 학습 위주로 실습 파일이 없습니다
📖 이론10분

"실패는 더 현명하게 다시 시작할 기회다."

— 헨리 포드 (Henry Ford, 포드 창업자)
🎯 오늘의 학습 목표
  • n8n AI Agent 실습 중 자주 만나는 오류 패턴을 파악한다.
  • 오류 메시지를 보고 빠르게 원인을 진단할 수 있다.
  • 해결책을 즉시 적용할 수 있다.
🚨 OpenAI / LLM 연결 오류
401 Unauthorized — Incorrect API key provided
OpenAI API 키가 잘못 입력되었습니다. n8n Credentials에서 OpenAI API 키를 다시 확인하고 저장하세요. 키 앞뒤 공백이 포함되지 않았는지 확인하세요.
bash
// 올바른 API 키 형식
sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
429 Too Many Requests — Rate limit exceeded
API 호출 한도를 초과했습니다. 잠시 기다리거나 OpenAI 플랜을 업그레이드하세요. 실습 중에는 gpt-4o-mini를 사용하면 한도가 더 높습니다.
400 Bad Request — This model's maximum context length is exceeded
입력 토큰이 모델 한도를 초과했습니다. Text Splitter의 Chunk Size를 줄이거나 더 긴 컨텍스트를 지원하는 gpt-4-turbo(128K)로 모델을 변경하세요.
AI Agent 노드가 무한 루프에 빠지는 경우
AI Agent 노드의 Max Iterations 값을 설정하세요. 기본값은 10이며, 테스트 시에는 5로 낮추는 것을 권장합니다.
bash
// AI Agent 노드 설정
Max Iterations: 5   // 테스트 시
Max Iterations: 10  // 운영 시
🚨 Supabase / 벡터 DB 오류
ERROR: function match_documents does not exist
Supabase에 match_documents 함수가 생성되지 않았습니다. DAY 19의 SQL을 Supabase SQL Editor에서 다시 실행하세요.
bash
-- Supabase SQL Editor에서 실행
create or replace function match_documents (
  query_embedding vector(1536),
  match_count int default 5,
  filter jsonb default '{}'
) returns table (
  id bigint,
  content text,
  metadata jsonb,
  similarity float
)
language plpgsql
as $$
begin
  return query
  select
    id, content, metadata,
    1 - (documents.embedding <=> query_embedding) as similarity
  from documents
  where metadata @> filter
  order by documents.embedding <=> query_embedding
  limit match_count;
end;

$$;
ERROR: column 'embedding' is of type vector but expression is of type text
임베딩 값이 벡터 형식이 아닌 텍스트로 전달되고 있습니다. Supabase Vector Store 노드의 Embedding 연결이 OpenAI Embeddings 노드와 올바르게 연결되어 있는지 확인하세요.
Supabase 노드 — Invalid API key
Supabase Credential에서 Project URL과 Service Role Key를 확인하세요. anon key가 아닌 service_role key를 사용해야 합니다.
bash
// Supabase Credential 설정
Host: https://xxxxxxxxxxxx.supabase.co
Service Role Secret: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
🚨 Tool / Sub-workflow 오류
Tool returned no output — Agent가 Tool 결과를 받지 못함
Tool로 등록된 Sub-workflow의 마지막 노드가 데이터를 반환하는지 확인하세요. Respond to Webhook 노드 또는 Return Data 설정이 필요합니다.
HTTP Request Tool — 401 / 403 오류
외부 API의 인증 방식을 확인하세요. Bearer Token, API Key Header, Basic Auth 중 어떤 방식인지 확인 후 HTTP Request Tool의 Authentication 설정을 변경하세요.
bash
// HTTP Request Tool 헤더 설정 예시
Authorization: Bearer {{$credentials.apiKey}}
Content-Type: application/json
Tavily Search — 401 Unauthorized
Tavily API 키가 만료되었거나 잘못되었습니다. app.tavily.com에서 새 API 키를 발급받고 n8n Credentials를 업데이트하세요.
🚨 메모리(Memory) 오류
Memory 노드 — Session ID가 매번 초기화됨
Chat Trigger를 사용하는 경우 Session ID를 {{ $('Chat Trigger').item.json.sessionId }}로 설정하세요. 고정 문자열을 사용하면 모든 사용자가 같은 메모리를 공유하게 됩니다.
bash
// Window Buffer Memory 노드 Session ID 설정
{{ $('Chat Trigger').item.json.sessionId }}
대화가 길어질수록 응답이 느려지거나 토큰 초과 발생
Window Buffer Memory의 Context Window Length를 줄이세요. 기본 10에서 5~6으로 낮추면 최근 대화만 기억합니다.
bash
// Window Buffer Memory 설정
Context Window Length: 5   // 최근 5턴만 기억
🚨 Notion / 외부 서비스 오류
Notion — Could not find database with ID
Notion 데이터베이스 ID가 잘못되었거나 Integration이 해당 데이터베이스에 연결되지 않았습니다. Notion에서 해당 데이터베이스 → Share → Integration을 추가하세요.
bash
// Notion 데이터베이스 ID 추출 방법
// URL: https://notion.so/workspace/DATABASE_ID?v=...
// DATABASE_ID 부분 (32자리 hex)을 복사하여 사용
Webhook Trigger — 응답 없음 (timeout)
워크플로우가 활성화(Active) 상태인지 확인하세요. 테스트 모드에서는 Webhook URL이 다릅니다. Production URL과 Test URL을 혼동하지 마세요.
n8n 계정이 없으신가요?n8n 무료 시작하기 ↗
← 부록 B
주요 AI 모델 비교표
목차로부록 D →
PART별 완료 체크리스트