Ollama Connection Refused 오류: 서버 연결 실패 해결 방법

Ollama Connection Refused 오류는 모델 자체보다 클라이언트가 지정한 주소와 포트에서 Ollama 서버를 만나지 못할 때 발생합니다. 서버가 꺼졌거나 11434 포트가 열리지 않은 경우, OLLAMA_HOST가 다른 주소에 binding된 경우, Docker·WSL 안에서 localhost의 대상이 달라진 경우를 먼저 구분해야 합니다. 이 글은 재설치나 방화벽 해제 전에 연결이 끊긴 지점을 단계별로 찾는 방법을 설명합니다.

Ollama Connection Refused 원인 진단표

1단계: 로컬 API가 응답하는지 확인

Ollama 공식 API 문서의 local base URL은 native API 기준 http://localhost:11434/api입니다. 모델 목록 endpoint로 서버 연결과 응답을 한 번에 검사합니다.

curl -v http://127.0.0.1:11434/api/tags

• HTTP/1.1 200과 models 배열: 서버 연결이 정상입니다.
• Connection refused: 해당 주소·포트에서 연결을 받는 서버가 없습니다.
• timeout: IP, routing, firewall과 proxy를 확인합니다.
• 404: 서버에는 연결됐지만 endpoint가 잘못됐습니다.
• 503: 연결 문제가 아니라 서버의 요청 처리 여유를 확인해야 합니다.

localhost가 IPv6 ::1로 해석되지만 서버는 IPv4에만 binding된 상황을 구분하려면 127.0.0.1도 직접 시험하세요.

curl -v http://localhost:11434/api/tags
curl -4 -v http://127.0.0.1:11434/api/tags

2단계: Ollama 서버를 시작하고 상태 확인

Windows

작업 표시줄에서 Ollama 앱이 실행 중인지 확인하고 시작 메뉴에서 다시 실행합니다. PowerShell에서는 다음 순서로 확인하세요.

ollama --version
Get-Process ollama -ErrorAction SilentlyContinue
Test-NetConnection 127.0.0.1 -Port 11434
Get-Content "$env:LOCALAPPDATA\Ollama\server.log" -Tail 100

앱을 완전히 종료한 뒤 직접 server를 실행하면 시작 단계의 오류를 terminal에서 볼 수 있습니다.

ollama serve

이미 port를 사용 중이라는 메시지가 나오면 다른 Ollama process나 프로그램이 11434를 점유한 것입니다. process를 임의 종료하기 전에 PID와 실행 파일을 확인하세요.

macOS

ollama --version
pgrep -fl Ollama
lsof -nP -iTCP:11434 -sTCP:LISTEN
tail -n 100 ~/.ollama/logs/server.log

menu bar 앱을 다시 시작한 뒤 API를 재검사합니다. 앱과 terminal의 ollama serve를 동시에 실행하지 말고 어느 process가 port를 소유하는지 확인하세요.

Linux systemd

sudo systemctl status ollama --no-pager
sudo systemctl start ollama
sudo journalctl -u ollama --no-pager -n 100
ss -ltnp | grep 11434

service가 반복 재시작된다면 Connection Refused는 결과일 뿐이며 실제 원인은 journal에 있습니다. ExecStart, 권한, 모델 경로 또는 GPU runner 오류를 시작 실패 시각과 함께 확인합니다.

3단계: 11434 포트를 누가 듣고 있는지 확인

process가 떠 있다는 사실과 원하는 주소에서 port를 LISTEN한다는 사실은 다릅니다.

127.0.0.1:11434만 표시되면 같은 운영체제 안에서만 접근할 수 있습니다. 0.0.0.0:11434는 여러 interface에서 받을 수 있다는 뜻이지만, 실제 접근 가능 여부는 host firewall과 network routing에도 좌우됩니다.

4단계: OLLAMA_HOST binding 수정하기

Ollama는 기본적으로 127.0.0.1:11434에 binding됩니다. 같은 PC에서만 사용할 때는 이 기본값이 가장 안전합니다. WSL·container·다른 기기에서 접근해야 할 때만 필요한 interface로 범위를 넓히세요.

Linux systemd

sudo systemctl edit ollama

[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"

sudo systemctl daemon-reload
sudo systemctl restart ollama
sudo systemctl show ollama --property=Environment
ss -ltnp | grep 11434

macOS 앱

launchctl setenv OLLAMA_HOST "0.0.0.0:11434"
launchctl getenv OLLAMA_HOST

환경 변수를 설정한 뒤 Ollama 앱을 완전히 종료하고 다시 시작합니다.

Windows 앱

Ollama를 tray에서 종료하고 Windows 사용자 환경 변수에 OLLAMA_HOST를 추가한 뒤 시작 메뉴에서 앱을 다시 실행합니다. 현재 PowerShell session에서만 시험한다면 다음처럼 직접 server를 시작할 수 있습니다.

$env:OLLAMA_HOST="0.0.0.0:11434"
ollama serve

보안 주의: 0.0.0.0 binding은 모든 interface에서 연결을 받을 수 있게 합니다. 공용 Wi-Fi나 인터넷에 11434를 그대로 노출하지 말고 host firewall에서 신뢰할 수 있는 사설 대역만 허용하거나 인증을 제공하는 reverse proxy·VPN을 사용하세요.

5단계: 클라이언트 주소와 API 경로 확인

서버가 정상이어도 client가 잘못된 base URL을 사용하면 연결에 실패합니다. 특히 client가 실행되는 위치를 기준으로 localhost의 뜻이 달라집니다.

Ollama 공식 API 문서가 구분하는 base URL이 다르므로 사용하는 SDK가 endpoint를 자동으로 덧붙이는지 확인하세요. 다만 경로가 잘못된 경우에는 보통 HTTP 404가 반환되며, Connection Refused라면 먼저 host와 port를 봐야 합니다.

6단계: Docker에서 localhost 오류 해결

container 안의 localhost는 host PC가 아니라 그 container 자신입니다. Ollama도 container에서 실행한다면 11434 port mapping이 있어야 host에서 접근할 수 있습니다.

docker ps --filter name=ollama
docker port ollama
docker logs --tail 100 ollama
curl -v http://127.0.0.1:11434/api/tags

Ollama 공식 Docker 예시는 다음처럼 host의 11434와 container의 11434를 연결합니다.

docker run -d \
  -v ollama:/root/.ollama \
  -p 11434:11434 \
  --name ollama \
  ollama/ollama

다른 container가 Ollama container에 접근한다면 두 container를 같은 Docker network에 두고 Ollama의 service 또는 container 이름을 host로 사용하세요. client container 내부에 http://localhost:11434를 넣으면 client 자신을 가리킵니다.

# 같은 Compose network의 개념 예시
OLLAMA_HOST=http://ollama:11434

환경 변수 이름은 사용하는 client마다 다를 수 있으므로 해당 앱의 설정 문서를 확인하세요. Ollama server의 binding 변수 OLLAMA_HOST와 client가 server 주소를 저장하는 변수를 혼동하지 않는 것이 중요합니다.

7단계: WSL에서 Windows Ollama 연결 확인

먼저 Windows PowerShell과 WSL 양쪽에서 같은 검사를 수행합니다.

# Windows PowerShell
curl.exe -v http://127.0.0.1:11434/api/tags

# WSL
curl -v http://127.0.0.1:11434/api/tags
ip route

Windows에서는 성공하지만 WSL에서 거부된다면 Windows Ollama가 loopback에만 binding됐는지, WSL의 localhost forwarding과 Windows firewall 정책이 어떻게 적용되는지 확인합니다. 외부 interface로 binding할 때는 Windows host의 실제 사설 IP로도 시험하되 공용 network에 port를 열지 마세요.

WSL 안에도 별도 Ollama를 설치했다면 어느 server를 사용할지 먼저 결정합니다. Windows 앱과 WSL service를 동시에 실행해 서로 다른 모델 목록과 port를 바라보는 상황을 피하세요.

8단계: 방화벽은 로컬 성공 후 확인하기

같은 PC의 127.0.0.1 요청부터 실패한다면 방화벽 규칙을 넓히기보다 server 실행과 binding을 고쳐야 합니다. 로컬은 성공하고 원격 client만 실패할 때 다음을 확인하세요.

1. server가 0.0.0.0:11434 또는 의도한 사설 interface에 LISTEN하는지 확인합니다.
2. client에서 server의 정확한 사설 IP와 port를 검사합니다.
3. host firewall은 신뢰할 수 있는 source IP·사설 대역만 허용합니다.
4. router port forwarding으로 인터넷에 직접 공개하지 않습니다.
5. 원격 사용은 VPN이나 인증·TLS를 제공하는 proxy 뒤에 배치합니다.

모든 방화벽을 끄는 방식은 원인 분리를 어렵게 하고 공격 표면을 넓힙니다. 필요한 interface와 source 범위만 최소한으로 허용하세요.

9단계: proxy와 CORS를 Connection Refused와 구분하기

Ollama 공식 FAQ는 모델 download용 proxy에 HTTPS_PROXY를 사용하고 HTTP_PROXY 설정은 client 연결을 방해할 수 있어 피하라고 안내합니다. 로컬 요청까지 proxy로 보내는 환경이라면 값을 기록한 뒤 우회 검사를 합니다.

# Linux·macOS
env | grep -i proxy
curl --noproxy '*' -v http://127.0.0.1:11434/api/tags

# PowerShell
Get-ChildItem Env: | Where-Object Name -Match 'PROXY'

브라우저에서 CORS 오류가 보인다면 TCP 연결은 이미 성립한 경우가 많습니다. OLLAMA_ORIGINS는 허용할 web origin을 설정하는 값이며 server가 11434에서 LISTEN하지 않는 Connection Refused를 고치지는 못합니다. wildcard를 바로 허용하기보다 실제 frontend origin만 추가하세요.

10단계: Nginx reverse proxy 확인

Ollama 공식 FAQ의 기본 proxy 구조는 요청을 local Ollama server로 전달합니다.

server {
  listen 80;
  server_name ai.example.internal;

  location / {
    proxy_pass http://localhost:11434;
    proxy_set_header Host localhost:11434;
  }
}

proxy에서 502가 나오면 Nginx 자체에는 도달했지만 upstream Ollama 연결에 실패했을 가능성이 큽니다. proxy host에서 curl http://localhost:11434/api/tags를 실행하고 Ollama binding과 Nginx error log를 함께 확인하세요. containerized Nginx의 localhost 역시 Nginx container 자신을 가리킵니다.

로그 위치와 확인 순서

Connection Refused가 발생한 시각, client URL, server의 LISTEN 주소와 process ID를 한 세트로 기록하세요. 공개 게시 전 사용자명, 내부 IP, token과 proxy credential은 제거합니다.

수정 후 재현 테스트

1. server host에서 127.0.0.1:11434/api/tags가 200인지 확인합니다.
2. LISTEN 주소와 server PID를 기록합니다.
3. client가 같은 host에 있는지 WSL·container·다른 PC인지 구분합니다.
4. client 위치에서 server의 정확한 주소로 같은 endpoint를 호출합니다.
5. native API·OpenAI 호환 API 중 client가 기대하는 base URL을 맞춥니다.
6. 마지막으로 짧은 chat 또는 generate 요청을 실행합니다.
7. 변경 전후 HTTP status와 오류 시간을 기록합니다.

Ollama Connection Refused 진단표 CSV 내려받기

하지 않는 것이 좋은 해결 방법

• 로컬 API 확인 없이 Ollama와 모델을 모두 삭제하지 않습니다.
• 원인을 모른 채 Windows·Linux firewall 전체를 끄지 않습니다.
• 0.0.0.0:11434를 인터넷에 그대로 공개하지 않습니다.
• CORS 설정으로 TCP Connection Refused를 해결하려고 하지 않습니다.
• Docker container에서 host를 뜻한다고 가정하고 localhost를 사용하지 않습니다.
• Ollama server의 OLLAMA_HOST와 client의 server URL 설정을 같은 용도로 보지 않습니다.
• 404·503·timeout을 모두 Connection Refused라고 부르지 않습니다.

최종 체크리스트

편집부 결론

Ollama Connection Refused는 모델을 다시 내려받아 해결할 문제가 아니라 client에서 server까지의 연결 경로를 확인할 문제입니다. server host의 loopback 요청, LISTEN 주소, client 위치와 대상 URL 순서로 검사하면 어느 경계에서 끊겼는지 빠르게 찾을 수 있습니다.

가장 중요한 기준은 로컬 API 응답입니다. 로컬도 실패하면 앱·service와 로그를 먼저 보고, 로컬만 성공하면 binding·Docker·WSL·firewall을 확인하세요. 외부 접근을 위해 범위를 넓혔다면 복구와 함께 접근 통제도 반드시 점검해야 합니다.

공식 문서와 함께 읽을 글

Ollama 공식 API base URL 확인하기

OLLAMA_HOST와 네트워크 설정 확인하기

운영체제별 Ollama 로그 확인하기

Docker 11434 port mapping 확인하기

Ollama 설치 경로와 모델 설정 해결하기

Ollama RAM·VRAM 부족 해결하기

Ollama CUDA·GPU 실행 실패 해결하기

CLI 연결과 실행 오류 진단 원칙 보기

자주 묻는 질문

Ollama Connection Refused는 무슨 뜻인가요?

client가 요청한 주소·port에서 연결을 받을 server를 찾지 못했거나 연결이 즉시 거부된 상태입니다. 모델 파일보다 server process, binding 주소와 client URL을 먼저 확인하세요.

Ollama의 기본 포트는 무엇인가요?

local Ollama server의 기본 port는 11434이며 기본 binding은 127.0.0.1:11434입니다. native API의 local base URL은 http://localhost:11434/api입니다.

ollama serve를 실행했는데 address already in use가 나옵니다

이미 다른 process가 같은 주소와 port를 사용 중입니다. Windows는 Get-NetTCPConnection, macOS는 lsof, Linux는 ss로 PID를 확인하고 앱과 수동 server를 중복 실행했는지 점검하세요.

로컬에서는 되는데 다른 컴퓨터에서 연결되지 않습니다

기본 loopback binding은 다른 기기에서 접근할 수 없습니다. 필요한 경우 OLLAMA_HOST를 사설 interface에 맞게 설정하고 firewall을 최소 범위로 허용하되 11434를 인터넷에 직접 공개하지 마세요.

Docker에서 localhost로 Ollama에 연결할 수 없는 이유는 무엇인가요?

container 안의 localhost는 해당 container 자신을 뜻합니다. Ollama container와 같은 network의 service 이름 또는 host 접근 주소를 사용하고, host에서 접근한다면 -p 11434:11434 mapping을 확인하세요.

Connection Refused와 timeout은 같은 오류인가요?

다릅니다. refused는 대상이 연결을 즉시 거부한 상황에 가깝고 timeout은 응답을 받지 못한 상태입니다. timeout에서는 IP, routing, firewall과 proxy를 더 우선적으로 확인합니다.

OLLAMA_ORIGINS를 설정하면 Connection Refused가 해결되나요?

아닙니다. OLLAMA_ORIGINS는 browser origin 허용 범위를 조정합니다. server가 port를 LISTEN하지 않는 TCP 연결 실패는 앱·service와 OLLAMA_HOST를 해결해야 합니다.

OpenAI 호환 client에는 어떤 URL을 넣어야 하나요?

공식 API 문서의 local OpenAI 호환 base URL은 http://localhost:11434/v1입니다. 사용하는 SDK가 endpoint를 자동 추가하는지 함께 확인하세요.

방화벽을 꺼도 연결되지 않으면 무엇을 봐야 하나요?

server process가 살아 있는지, 11434를 어떤 주소에서 LISTEN하는지, client의 localhost가 어느 환경을 가리키는지 확인하세요. 방화벽은 로컬 API가 성공한 뒤 원격 연결만 실패할 때 점검하는 것이 안전합니다.