npm E401 Hatası: Kimlik Doğrulama Sorununu Çözme

Giriş

npm komutlarını çalıştırırken (örneğin npm install veya npm publish) aşağıdaki hatayı alıyorsunuz mu?

npm error code E401
npm error Unable to authenticate, your authentication token seems to be invalid.
npm error To correct this please try logging in again with:
npm error npm login

Bu hata, HTTP 401 (Yetkisiz Erişim) durum koduna karşılık gelir ve npm’nin paket kayıt defterine gönderdiği kimlik doğrulama token’ının geçersiz, süresi dolmuş veya yanlış kayıt defterine yönlendirilmiş olduğunu gösterir. Bu durum genellikle aşağıdaki senaryolarda ortaya çıkar:

• Özel kayıt defterleri (npm’in ücretli katmanı, GitHub Packages, Verdaccio, Artifactory veya Nexus)
• Kapsamlı (scoped) paketler için özel kayıt defteri yapılandırması
• Token’ın süresinin dolması veya iptal edilmesi
• .npmrc dosyasındaki yanlış yapılandırma

Bu kılavuzda, E401 hatasının nedenlerini analiz edecek, doğru kayıt defterini doğrulayacak, token yenileyecek ve .npmrc ayarlarını düzelteceksiniz. Adım adım ilerleyerek sorunu çözebilirsiniz.

E401 Hatasının Anlamı

HTTP 401 hatası, kayıt defterine yapılan isteğin kimlik doğrulama gerektirdiğini, ancak gönderilen token’ın geçersiz olduğunu belirtir. Bu durum aşağıdaki nedenlerden kaynaklanabilir:

• Token süresi dolmuş veya iptal edilmiş: Kayıt defteri, token’ın geçerlilik süresini kontrol eder. Süresi dolan veya iptal edilen token’lar reddedilir.
• Yanlış kayıt defteri: Token, projenizin kullandığı kayıt defterine ait değil. Örneğin, @myorg kapsamlı paketler için https://registry.example.com/ kayıt defteri kullanılırken, token sadece https://registry.npmjs.org/ için geçerli olabilir.
• .npmrc dosyasında eksik veya yanlış ayarlar: Token, kayıt defteri için doğru şekilde yapılandırılmamış olabilir.
• Yetkisiz token: Token, sadece okuma izni verirken, paket yayınlama (npm publish) gibi yetkili işlemler için kullanılıyor olabilir.

Adım 1: Kullanılan Kayıt Defterini Doğrulama

E401 hatasını çözmeye başlamadan önce, npm’nin hangi kayıt defterine erişmeye çalıştığını doğrulamanız gerekir. Yanlış kayıt defteri, geçerli bir token olsa bile hataya neden olabilir.

Varsayılan Kayıt Defterini Kontrol Etme

npm’nin varsayılan kayıt defterini görmek için aşağıdaki komutu çalıştırın:

npm config get registry

Çıktı genellikle aşağıdaki gibi olacaktır:

https://registry.npmjs.org/

Kapsamlı Paketler için Özel Kayıt Defterini Kontrol Etme

Projenizde @myorg gibi bir kapsam (scope) kullanılıyorsa, bu kapsamın hangi kayıt defterine yönlendirildiğini kontrol edin. Aşağıdaki komutu çalıştırın (örneğin @myorg yerine kendi kapsamınızı kullanın):

npm config get @myorg:registry

Eğer çıktı boşsa, npm varsayılan kayıt defterini kullanacaktır. Özel bir kayıt defteri kullanıyorsanız, aşağıdaki gibi bir çıktı alabilirsiniz:

https://registry.example.com/

Önemli Not

Uyarı: Kapsamlı paketler için kayıt defteri ayarı, @scope:registry=https://registry.example.com/ şeklinde .npmrc dosyasında da tanımlanabilir. Bu ayarı kontrol etmek için aşağıdaki komutu kullanabilirsiniz:

cat ~/.npmrc | grep @myorg:registry

Adım 2: Token Yenileme

E401 hatasının en yaygın nedenlerinden biri, token’ın süresinin dolmuş veya iptal edilmiş olmasıdır. Token’ı yenilemek için aşağıdaki adımları izleyin.

Genel Token Yenileme (npmjs.org)

npmjs.org kayıt defteri için token yenilemek için aşağıdaki komutu çalıştırın:

npm login

Bu komut, size npm hesabınıza giriş yapmanızı isteyecektir. Başarılı girişten sonra, token otomatik olarak ~/.npmrc dosyasına kaydedilecektir.

Özel Kayıt Defteri için Token Yenileme

Özel bir kayıt defteri (örneğin GitHub Packages, Verdaccio veya Artifactory) için token yenilemek üzere aşağıdaki komutu kullanın:

npm login --scope=@myorg --registry=https://registry.example.com/

Bu komut, hem kapsamı hem de kayıt defterini belirterek token’ın doğru şekilde kaydedilmesini sağlar.

Token’ın Geçerli Olduğunu Doğrulama

Token yenileme işleminden sonra, kayıt defterinin sizi tanıdığını doğrulamak için aşağıdaki komutu çalıştırın:

npmjs.org için:

npm whoami

Özel kayıt defteri için:

npm whoami --registry=https://registry.example.com/

Eğer komut kullanıcı adınızı döndürürse, token geçerlidir. Aksi takdirde, token’ın doğru kayıt defterine kaydedilmediğini veya yetkisiz olduğunu gösterir.

Adım 3: .npmrc Dosyasını İnceleme ve Düzeltme

npm, kimlik doğrulama bilgilerini .npmrc dosyalarından okur. Bu dosyalar, proje düzeyinde (./.npmrc) ve kullanıcı düzeyinde (~/.npmrc) bulunabilir. Token’ın doğru şekilde kaydedildiğinden emin olmak için aşağıdaki adımları izleyin.

.npmrc Dosyasını Açma

.npmrc dosyasını düzenlemek için aşağıdaki komutu çalıştırın:

nano ~/.npmrc

Not: Terminalde dosyayı görüntülemek yerine bir metin editörü kullanın, çünkü dosya hassas token bilgileri içerebilir.

Geçerli Token Yapılandırmasını Kontrol Etme

Aşağıda, npmjs.org kayıt defteri için geçerli bir token yapılandırması örneği verilmiştir:

//registry.npmjs.org/:_authToken=npm_xxxxxxxxxxxxxxxxxxxx

Bu satırda:

• //registry.npmjs.org/: Kayıt defterinin URL’si.
• :_authToken: Token’ın saklandığı anahtar.
• npm_xxxxxxxxxxxxxxxxxxxx: Token değeri.

Özel bir kayıt defteri için yapılandırma örneği:

//npm.pkg.github.com/:_authToken=ghp_xxxxxxxxxxxxxxxxxxxx
@myorg:registry=https://npm.pkg.github.com/

Yapılandırmayı Düzeltme

Eğer .npmrc dosyasında token satırı eksik, yanlış veya yanlış kayıt defterine yönlendirilmişse, aşağıdaki adımları izleyin:

1. .npmrc dosyasını açın.
2. Token satırını doğru kayıt defteri için ekleyin veya düzeltin.
3. Dosyayı kaydedin ve kapatın.
4. npm komutunu tekrar çalıştırın.

Token Yetkilerini Kontrol Etme

Uyarı: Token’ın yetkileri, gerçekleştireceğiniz işleme uygun olmalıdır. Örneğin:

• npm install için token’ın okuma izni olmalıdır.
• npm publish için token’ın yayınlama izni olmalıdır.

Yetkisiz bir token kullanırsanız, E401 hatası alırsınız.

Adım 4: CI/Docker Ortamlarında E401 Hatasını Çözme

CI/CD ortamlarında (GitHub Actions, GitLab CI/CD, Jenkins vb.) npm login komutu çalıştırılamaz. Bu nedenle, token genellikle ortam değişkenlerinden alınır. Aşağıdaki adımları izleyerek CI ortamında E401 hatasını çözebilirsiniz.

.npmrc Dosyasını CI Ortamında Oluşturma

CI ortamında, token’ı ortam değişkeninden alan bir .npmrc dosyası oluşturun. Örneğin, NPM_TOKEN ortam değişkenini kullanarak:

echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc

Bu komut, .npmrc dosyasına token’ı ortam değişkeninden alır ve dosyaya kaydeder. Token’ın kaydedilmediğine dikkat edin, çünkü ortam değişkeninden okunacaktır.

CI Ortamında Token’ın Doğruluğunu Kontrol Etme

CI ortamında token’ın doğru şekilde yapılandırıldığını doğrulamak için aşağıdaki komutu çalıştırın:

npm config get registry

Bu komut, npm’nin hangi kayıt defterini kullandığını gösterir. Token’ın bu kayıt defteri için geçerli olduğundan emin olun.

CI Ortamında Token Yetkilerini Ayarlama

İpucu: CI ortamında token’ın yetkilerini sınırlamak için aşağıdaki adımları izleyin:

• Token’ı en az yetkiyle oluşturun (örneğin, sadece okuma izni).
• Token’ın süresini mümkün olduğunca kısa tutun.
• Token’ı CI ortamının gizli değişkenlerinde saklayın.

Adım 5: Sık Karşılaşılan Sorunlar ve Çözümleri

npm whoami Komutu E401 Döndürüyor

Sorun: Token yenileme işleminden sonra npm whoami komutu E401 hatası döndürüyor.

Çözüm:

• Token’ın doğru kayıt defterine kaydedildiğinden emin olun.
• npm whoami komutunu doğru kayıt defteri için çalıştırın (örneğin, npm whoami --registry=https://registry.example.com/).
• .npmrc dosyasını hem kullanıcı hem de proje düzeyinde kontrol edin.
• Token’ın yetkilerini yeniden oluşturun.

npm install Başarılı, ancak npm publish Başarısız

Sorun: Paket yükleme başarılı, ancak yayınlama işlemi E401 hatasıyla başarısız oluyor.

Çözüm:

• Token’ın yayınlama yetkisine sahip olduğundan emin olun.
• Token’ı yayınlama yetkisiyle yeniden oluşturun.
• .npmrc dosyasındaki token satırını güncelleyin.

Sadece Bir Kapsamlı Paket için Hata Alınıyor

Sorun: Sadece @myorg gibi bir kapsamlı paket için E401 hatası alınıyor.

Çözüm:

• @myorg:registry=https://registry.example.com/ satırını .npmrc dosyasına ekleyin.
• //registry.example.com/:_authToken=... satırını ekleyin ve token’ı bu kayıt defteri için güncelleyin.

En İyi Uygulamalar

• Token’ı Ortam Değişkenlerinde Saklayın: Token’ı doğrudan .npmrc dosyasına yazmak yerine ortam değişkenlerinden alın. Örneğin:

  //registry.npmjs.org/:_authToken=${NPM_TOKEN}

• .npmrc Dosyasını Git’e Yüklemeyin: Proje düzeyindeki .npmrc dosyasını .gitignore listesine ekleyin.
• Token Yetkilerini Sınırlayın: Token’ı en az yetkiyle oluşturun ve mümkün olduğunca kısa sürede yenileyin.
• CI Ortamında Token’ı Gizli Değişkenlerde Saklayın: Token’ı CI ortamının gizli değişkenlerinde saklayın ve .npmrc dosyasına ortam değişkeni olarak ekleyin.

Sonuç

npm E401 hatası, genellikle token’ın süresinin dolması, yanlış kayıt defterine yönlendirilmesi veya .npmrc dosyasındaki yanlış yapılandırmadan kaynaklanır. Bu kılavuzda, hatanın nedenlerini analiz ettiniz, doğru kayıt defterini doğruladınız, token’ı yenilediniz ve .npmrc dosyasını düzelttiniz. Bu adımları izleyerek, E401 hatasını çözebilir ve npm komutlarınızı sorunsuz bir şekilde çalıştırabilirsiniz.

Ek Kaynaklar:

• npmrc Dokümantasyonu
• npm Token Yönetimi
• GitHub Packages Kullanımı