---
title: "Mac의 “npm error code ENOTFOUND” · Kilobat 가이드"
url: "https://kilobat.app/ko/guides/npm-enotfound"
description: "Mac의 npm install이 npm error code ENOTFOUND로 멈춥니다. 레지스트리 이름이 확인되지 않았습니다. DNS, 레지스트리 설정, VPN, 프록시를 확인하세요."
---

# Mac의 “npm error code ENOTFOUND”

ENOTFOUND는 DNS 조회 실패를 알립니다. Node.js 문서는 이를 EAI_NODATA 또는 EAI_NONAME 중 하나의 실패인 “DNS lookup failed”라고 설명합니다.

**에이전트로 해결하기**Claude Code, Codex 또는 터미널을 쓸 수 있는 에이전트용 프롬프트를 복사합니다.

제 Mac에 이런 문제가 있습니다: Mac의 “npm error code ENOTFOUND”. https://kilobat.app/ko/guides/npm-enotfound.md을(를) 읽고 저와 함께 해결해 주세요. Kilobat CLI가 없으면 설치해 주세요: brew install seifip/kilobat/kilobat. 가이드의 터미널 및 kilobat 점검은 직접 실행하고, 알아낸 내용을 알려 주세요. 저만 할 수 있는 단계는 목록으로 정리해 주세요. 설정을 바꾸기 전에는 먼저 물어봐 주세요.

적용 대상: npm 10 이상은 “npm error”를 출력하고, 이전 버전은 “npm ERR!”를 출력합니다. 현재의 모든 macOS 버전의 Node.js. · 확인일: 2026년 10월 29일

## 증상

- `npm install`이(가) `npm error code ENOTFOUND` 메시지와 함께 중단됩니다.
- 다음 줄에 `registry.npmjs.org` 같은 호스트가 표시됩니다.
- 브라우저는 작동할 수 있습니다.

## 가능한 원인

- **연결 또는 DNS 없음.** Mac이 DNS 서버에 도달하지 못합니다.
- **잘못된 레지스트리.** npm 레지스트리 설정이 존재하지 않거나 VPN이 필요한 호스트를 가리킵니다.
- **자체 DNS를 쓰는 VPN.** 회사 레지스트리는 VPN이 켜져 있는 동안에만 확인됩니다.
- **npm이 사용하지 않는 프록시.** 프록시 전용 네트워크에서는 npm에 프록시 설정이 필요합니다.

## 확인 방법

1. npm이 사용하는 레지스트리를 표시하세요.

   ```
   npm config get registry
   ```
2. macOS를 통해 호스트 이름을 확인하세요.

   ```
   dscacheutil -q host -a name registry.npmjs.org
   ```
3. 레지스트리에 직접 물어보세요.

   ```
   npm ping
   ```
4. 프록시 설정을 표시하세요.

   ```
   npm config get https-proxy
   ```

## 해결 방법

1. macOS 조회가 실패하면 DNS를 해결하세요. [Mac에서 DNS가 확인되지 않을 때](https://kilobat.app/ko/guides/dns-server-not-found)를 참고하세요.
2. 레지스트리를 바로잡으세요.

   ```
   npm config set registry https://registry.npmjs.org/
   ```
3. 회사 레지스트리라면 VPN을 연결하세요.
4. DNS 캐시를 지우세요. [Mac에서 DNS 캐시 지우기](https://kilobat.app/ko/guides/flush-dns-cache-mac)를 참조하세요.

## Kilobat 사용

1. Kilobat의 연결 진단은 주소를 네트워크, 프록시, DNS, 규칙, IPv4, IPv6, TLS, 서버의 계층별로 테스트합니다. 실패한 계층을 알려줍니다.

   ```
   kilobat why https://registry.npmjs.org/
   ```
2. 이 Kilobat 검사는 무료입니다. AI 에이전트는 MCP를 통해 `diagnose_connection` 및 `diagnose_network`(으)로 실행합니다. [특정 사이트나 API에 연결되지 않는 이유 찾기](https://kilobat.app/ko/guides/recipes/why-cant-it-connect)를 참조하세요.

## 질문

**ENOTFOUND는 EAI_AGAIN과 같은 오류인가요?**

아니요. EAI_AGAIN은 일시적인 조회 실패를 알립니다. [Mac의 EAI_AGAIN](https://kilobat.app/ko/guides/eai-again)을 참고하세요.

**패키지 이름이 틀렸나요?**

드뭅니다. ENOTFOUND는 패키지 이름이 아니라 호스트 이름에 관한 것입니다.

## 출처

- [Node.js 문서: 일반적인 시스템 오류](https://nodejs.org/api/errors.html#common-system-errors)
- [npm 문서: 흔한 오류](https://docs.npmjs.com/common-errors)

2026년 10월 29일 확인했습니다.

## 관련 가이드

- [Mac에서 “npm error code ECONNRESET”](https://kilobat.app/ko/guides/npm-econnreset): ECONNRESET은 강제로 재설정된 연결을 나타냅니다.
- [Mac에서 “npm error code ETIMEDOUT” 발생](https://kilobat.app/ko/guides/npm-etimedout): ETIMEDOUT은 상대방이 제때 응답하지 않았음을 의미합니다.
- [Mac의 EAI_AGAIN](https://kilobat.app/ko/guides/eai-again): EAI_AGAIN은 현재 이름을 해석할 수 없음을 나타냅니다.
- [Mac에서 “curl: (6) Could not resolve host”](https://kilobat.app/ko/guides/curl-could-not-resolve-host): curl 종료 코드 6은 curl이 호스트 이름의 주소를 가져오지 못했다는 뜻입니다.
