Laravel CORS Hatası Nasıl Çözülür? 2026 Rehberi

Laravel CORS hatası, frontend ile Laravel API veya backend farklı domain, subdomain ya da port üzerinden çalıştığında ortaya çıkabilir. Tarayıcı güvenlik politikaları nedeniyle istek engellenir ve genellikle Access-Control-Allow-Origin veya CORS policy ifadeleri görülür.

Bu rehberde Laravel CORS hatasının nedenlerini, config/cors.php ayarlarını, API isteklerini, Sanctum kullanımını, credentials sorunlarını ve production ortamındaki doğru yapılandırmayı adım adım ele alacağız.

Laravel CORS Nedir?

CORS, Cross-Origin Resource Sharing ifadesinin kısaltmasıdır. Bir web uygulamasının farklı bir origin üzerinde bulunan sunucuya HTTP isteği göndermesine izin veren mekanizmadır.

Örneğin frontend uygulamanız https://app.site.com, Laravel API'niz ise https://api.site.com adresindeyse tarayıcı bu iki adresi farklı origin olarak değerlendirebilir.

Aşağıdaki durumlarda CORS problemiyle karşılaşabilirsiniz:

• Farklı domain kullanılması
• Farklı subdomain kullanılması
• Farklı port kullanılması
• HTTP ve HTTPS arasında geçiş yapılması
• API'nin farklı bir frontend tarafından tüketilmesi
• Laravel Sanctum kullanılması
• OPTIONS preflight isteğinin engellenmesi

Laravel CORS Hatası Neden Olur?

En yaygın nedenlerden biri Laravel'in isteği gönderen origin'e izin vermemesidir.

Örneğin frontend https://panel.example.com üzerinden API'ye istek gönderiyor ancak Laravel tarafında yalnızca https://example.com izin verilen origin olarak tanımlanmışsa tarayıcı isteği engelleyebilir.

Tarayıcı konsolunda genellikle şu tarz mesajlar görülür:

Access to XMLHttpRequest has been blocked by CORS policy

veya

No 'Access-Control-Allow-Origin' header is present

Laravel CORS Ayarları Nerede?

Laravel sürümüne ve kurulum yapısına göre CORS yapılandırması farklılık gösterebilir.

Çoğu Laravel projesinde yapılandırma dosyası:

config/cors.php

dosyasıdır.

Dosya mevcut değilse Laravel sürümünüzde CORS yapılandırmasının nasıl sağlandığını kontrol etmeniz gerekir.

config/cors.php Nasıl Yapılandırılır?

Örnek bir yapılandırma şu şekilde olabilir:

'paths' => ['api/*', 'sanctum/csrf-cookie'],

'allowed_methods' => ['*'],

'allowed_origins' => ['https://example.com'],

'allowed_origins_patterns' => [],

'allowed_headers' => ['*'],

'exposed_headers' => [],

'max_age' => 0,

'supports_credentials' => false,

Buradaki en önemli alanlardan biri allowed_origins değeridir.

allowed_origins Ne İşe Yarar?

allowed_origins, Laravel API'sine hangi originlerin erişebileceğini belirler.

Örneğin:

'allowed_origins' => ['https://example.com'],

yalnızca belirtilen origin için izin tanımlar.

Frontend'iniz:

https://panel.example.com

üzerindeyse doğrudan https://example.com yazmanız yeterli olmayabilir.

Şunu kullanmanız gerekir:

'allowed_origins' => ['https://panel.example.com'],

Birden Fazla Domain İçin CORS Ayarı

Birden fazla frontend kullanıyorsanız originleri listeleyebilirsiniz:

'allowed_origins' => ['https://example.com', 'https://panel.example.com', 'https://app.example.com'],

Bu yöntem production ortamında hangi adreslerin API'ye erişebileceğini açıkça belirlemek açısından daha kontrollüdür.

allowed_methods Ayarı

API'nizde GET, POST, PUT, PATCH ve DELETE gibi farklı HTTP metotları kullanıyorsanız bunların CORS üzerinden izinli olması gerekir.

Tüm metotlara izin vermek için:

'allowed_methods' => ['*'],

Belirli metotları kullanmak için:

'allowed_methods' => ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],

Production ortamında ihtiyacınız olmayan HTTP metotlarını gereksiz yere açmamak daha kontrollü bir yapı sağlayabilir.

allowed_headers Ayarı

İstek içerisinde kullanılan HTTP header bilgilerinin kabul edilmesini sağlar.

Genel bir yapı:

'allowed_headers' => ['*'],

Belirli headerlar kullanılacaksa:

'allowed_headers' => ['Content-Type', 'Authorization', 'X-Requested-With', 'Accept'],

JWT veya Bearer token kullanılan API'lerde Authorization header'ının dikkate alınması önemlidir.

Laravel CORS OPTIONS Hatası

CORS problemlerinin en çok karıştırılan noktalarından biri OPTIONS isteğidir.

Tarayıcı bazı cross-origin isteklerden önce sunucuya OPTIONS isteği gönderir. Buna preflight request denir.

Örneğin frontend:

POST /api/orders

göndermeden önce:

OPTIONS /api/orders

isteği gönderebilir.

Sunucu bu isteğe uygun CORS headerlarıyla cevap vermezse asıl POST isteği gönderilmeden tarayıcı tarafından engellenebilir.

OPTIONS İsteği Neden Önemlidir?

Özellikle aşağıdaki durumlarda preflight isteği görülebilir:

• Authorization header kullanılması
• JSON içerik gönderilmesi
• PUT veya DELETE kullanılması
• Özel HTTP headerlarının eklenmesi
• Cross-origin API çağrıları

Bu nedenle yalnızca POST veya GET route'unu kontrol etmek yeterli olmayabilir.

Laravel CORS ve Sanctum

Laravel Sanctum kullanıyorsanız CORS ayarlarına ek olarak session ve stateful domain yapılandırmasını da kontrol etmeniz gerekir.

Örneğin:

'paths' => ['api/*', 'sanctum/csrf-cookie'],

Frontend domaininin Sanctum tarafından stateful olarak kabul edilmesi de gerekebilir.

.env içerisinde kullanılan domain ayarlarının doğru olduğundan emin olun.

Örneğin:

SANCTUM_STATEFUL_DOMAINS=panel.example.com

Port kullanılan local geliştirme ortamında ise:

SANCTUM_STATEFUL_DOMAINS=localhost:3000

gibi bir yapı gerekebilir.

supports_credentials Nedir?

Cookie veya session tabanlı authentication kullanıyorsanız:

'supports_credentials' => true,

gerekebilir.

Ancak burada önemli bir CORS kuralı vardır.

Credentials kullanılırken origin tarafında genel wildcard kullanmak doğru yaklaşım değildir.

Örneğin:

'allowed_origins' => ['*'],

ile:

'supports_credentials' => true,

birlikte kullanıldığında tarayıcı tarafında CORS problemleri yaşanabilir.

Bunun yerine gerçek frontend domainini belirtmek daha doğru olur:

'allowed_origins' => ['https://panel.example.com'],

Laravel CORS ve credentials Kullanımı

Frontend tarafında cookie gönderiyorsanız istemci tarafında da credentials desteğinin açık olması gerekebilir.

Axios örneğinde:

axios.defaults.withCredentials = true;

Fetch kullanıyorsanız:

fetch(url, { credentials: 'include' })

kullanılabilir.

Bunun Laravel tarafındaki supports_credentials ayarıyla uyumlu olması gerekir.

CORS Ayarından Sonra Cache Temizleme

Laravel yapılandırma dosyaları cache'lenmişse yaptığınız değişiklik hemen uygulanmayabilir.

Öncelikle:

php artisan optimize:clear

çalıştırabilirsiniz.

Alternatif olarak:

php artisan config:clear

komutu kullanılabilir.

Ardından API isteğini yeniden deneyin.

Laravel CORS Hatası Devam Ediyorsa

CORS ayarını değiştirdiğiniz halde hata devam ediyorsa problemi yalnızca config/cors.php dosyasında aramayın.

Şunları kontrol edin:

php artisan route:list

Ardından tarayıcı geliştirici araçlarından Network sekmesini açın.

Özellikle şu isteklere bakın:

OPTIONS

GET

POST

PUT

PATCH

DELETE

OPTIONS isteğinin HTTP durum kodunu ve response headerlarını kontrol edin.

Response Headerlarını Kontrol Etme

Başarılı bir CORS yanıtında kullanılan headerlardan biri:

Access-Control-Allow-Origin

olabilir.

Credentials kullanılıyorsa:

Access-Control-Allow-Credentials: true

gibi bir header da görülebilir.

Browser Developer Tools → Network → ilgili istek → Headers bölümünden bu değerleri inceleyebilirsiniz.

Laravel CORS ve Nginx

Laravel doğru yapılandırılmış olsa bile Nginx katmanında yapılan özel header veya location ayarları CORS davranışını etkileyebilir.

Özellikle reverse proxy, API gateway veya CDN kullanılıyorsa isteğin Laravel'e ulaşmadan önce değiştirilip değiştirilmediğini kontrol etmek gerekir.

Bu nedenle sadece Laravel dosyasına bakmak bazı production problemlerinde yeterli olmayabilir.

Laravel CORS ve Apache

Apache kullanılan hostinglerde .htaccess veya VirtualHost yapılandırması da kontrol edilmelidir.

Özellikle API'nin Laravel'e ulaşmadan önce Apache tarafından yönlendirilmesi, engellenmesi veya farklı headerlarla cevap verilmesi CORS problemlerine neden olabilir.

cPanel hosting kullanıyorsanız hosting sağlayıcısının Apache/PHP yapılandırması da önemlidir.

CORS İçin Wildcard Kullanmak Güvenli mi?

Geliştirme sırasında:

'allowed_origins' => ['*'],

kullanmak problemi teşhis etmeyi kolaylaştırabilir.

Ancak production API'sinde tüm originlere izin vermek her zaman uygun değildir.

Özellikle authentication, cookie veya özel kullanıcı verileri içeren API'lerde hangi originlerin erişebileceğini açıkça belirlemek daha kontrollü bir yaklaşımdır.

Localhost CORS Hatası

Local geliştirme sırasında frontend:

http://localhost:3000

Laravel:

http://localhost:8000

üzerindeyse bunlar farklı originlerdir.

CORS ayarında frontend adresini belirtmeniz gerekebilir:

'allowed_origins' => ['http://localhost:3000'],

Frontend portunuz 5173 ise:

'allowed_origins' => ['http://localhost:5173'],

şeklinde ayarlamalısınız.

HTTP ve HTTPS CORS Problemi

Production ortamında frontend:

https://example.com

API:

http://api.example.com

şeklindeyse yalnızca CORS değil, mixed content ve güvenlik problemleri de ortaya çıkabilir.

Production ortamında frontend ve API'nin HTTPS üzerinden çalışması daha doğru bir yapı oluşturur.

Laravel CORS Hatasını Adım Adım Çözme

İlk olarak frontend adresini belirleyin.

Örneğin:

https://panel.example.com

Ardından Laravel CORS yapılandırmasında bu originin tanımlı olduğunu kontrol edin.

Sonra:

php artisan optimize:clear

çalıştırın.

Ardından:

php artisan route:list

ile API route'larını kontrol edin.

Tarayıcı Developer Tools → Network bölümünden OPTIONS isteğini inceleyin.

Son olarak response headerlarını kontrol edin.

Bu adımlar çoğu CORS probleminin kaynağını belirlemenize yardımcı olur.

Production Laravel CORS İçin Örnek Yapı

Gerçek bir production API'sinde örneğin:

'paths' => ['api/*', 'sanctum/csrf-cookie'],

'allowed_methods' => ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],

'allowed_origins' => ['https://panel.example.com'],

'allowed_headers' => ['Content-Type', 'Authorization', 'X-Requested-With', 'Accept'],

'exposed_headers' => [],

'max_age' => 0,

'supports_credentials' => true,

gibi bir yapı kullanılabilir.

Ancak bu değerler projenizin authentication ve frontend mimarisine göre değiştirilmelidir.

Laravel CORS Hatasında Yapılmaması Gerekenler

CORS sorununu çözmek için doğrudan her şeyi * yapmak iyi bir production stratejisi değildir.

Ayrıca:

• 777 gibi gereksiz dosya izinleri vermeyin.
• Authentication kullanılan API'lerde originleri kontrolsüz açmayın.
• CORS problemini yalnızca frontend hatası olarak değerlendirmeyin.
• OPTIONS isteklerini göz ardı etmeyin.
• Cache temizlemeden yapılandırma değişikliğinin uygulanmadığını varsaymayın.
• HTTPS kullanılan sistemde HTTP API bırakmayın.

Laravel CORS Hatası İçin Hızlı Kontrol Listesi

config/cors.php mevcut mu?

Frontend domaini allowed_origins içerisinde mi?

API path'i paths içerisinde mi?

OPTIONS isteği başarılı mı?

Access-Control-Allow-Origin headerı geliyor mu?

Credentials kullanılıyorsa supports_credentials doğru mu?

Sanctum kullanılıyorsa stateful domain doğru mu?

Laravel config cache temizlendi mi?

Nginx veya Apache CORS davranışını değiştiriyor mu?

CDN veya proxy arada headerları değiştiriyor mu?

Bu listeyi takip ederek problemi sistematik şekilde izole edebilirsiniz.

Sık Sorulan Sorular

1. Laravel CORS hatası nedir?

Laravel API ile farklı bir origin üzerinden çalışan frontend arasındaki cross-origin isteğin tarayıcı tarafından engellenmesiyle ortaya çıkan sorundur.

2. Laravel CORS ayarı nerede yapılır?

Laravel projelerinde CORS yapılandırması genellikle config/cors.php dosyası üzerinden yapılır.

3. Laravel CORS neden çalışmıyor?

Yanlış origin, eksik path, OPTIONS isteğinin engellenmesi, cache veya web sunucusu yapılandırması nedeniyle çalışmayabilir.

4. Laravel CORS için allowed_origins nedir?

allowed_origins, API'ye hangi originlerin cross-origin istek gönderebileceğini belirleyen yapılandırmadır.

5. Laravel CORS için * kullanılabilir mi?

Teknik olarak wildcard kullanılabilir ancak production ve authentication içeren sistemlerde hangi originlerin izinli olduğunu açıkça belirtmek daha kontrollüdür.

6. Laravel CORS OPTIONS hatası nasıl çözülür?

OPTIONS isteğinin API sunucusu tarafından doğru şekilde karşılandığını ve gerekli CORS response headerlarının gönderildiğini kontrol edin.

7. Laravel CORS ve Sanctum birlikte nasıl çalışır?

Sanctum kullanılan uygulamalarda CORS ayarlarının yanında stateful domain, CSRF cookie ve credentials yapılandırmasının da uyumlu olması gerekir.

8. Laravel supports_credentials ne işe yarar?

Cookie veya session gibi kimlik doğrulama bilgilerinin cross-origin isteklerle kullanılmasına yönelik CORS davranışını kontrol eder.

9. CORS hatası frontend kaynaklı mıdır?

Her zaman değildir. Laravel, web sunucusu, proxy, CDN ve frontend yapılandırmasının herhangi birindeki problem CORS hatasına neden olabilir.

10. Laravel CORS değişikliğinden sonra neden düzelmiyor?

Laravel config cache kullanıyorsa eski yapılandırma aktif kalabilir. php artisan optimize:clear ile cache temizlenebilir.

11. Laravel localhost CORS hatası neden verir?

localhost üzerindeki farklı portlar farklı origin kabul edilir. Örneğin 3000 ve 8000 portları aynı origin değildir.

12. Laravel API için hangi HTTP metotlarına izin verilmelidir?

Uygulamanın ihtiyacına göre GET, POST, PUT, PATCH, DELETE ve gerekli durumlarda OPTIONS izin verilen metotlar arasında bulunabilir.

13. Laravel CORS Authorization header hatası nasıl çözülür?

Authorization header kullanılıyorsa CORS allowed_headers yapılandırmasında Authorization headerının kabul edildiğinden emin olun.

14. Laravel CORS ve Axios birlikte çalışmıyor, neden?

Axios tarafından gönderilen credentials, Authorization veya özel headerların Laravel CORS yapılandırmasıyla uyumlu olması gerekir.

15. Laravel CORS ve Fetch nasıl yapılandırılır?

Fetch kullanılan uygulamalarda özellikle cookie tabanlı authentication varsa credentials seçeneğinin backend CORS ayarlarıyla uyumlu olması gerekir.

16. Laravel CORS 403 hatasına neden olur mu?

Yanlış sunucu veya uygulama yapılandırması sonucunda CORS ile birlikte 403 görülebilir. Ancak 403 doğrudan her zaman CORS anlamına gelmez.

17. Laravel CORS 419 hatasıyla ilişkili mi?

Sanctum veya session tabanlı yapılarda CSRF yapılandırması yanlışsa CORS problemleriyle birlikte 419 Page Expired hatası görülebilir.

18. Laravel CORS production ortamında nasıl ayarlanmalı?

Production ortamında kullanılacak gerçek frontend originlerinin açıkça belirtilmesi, gereksiz wildcard kullanımından kaçınılması ve HTTPS kullanılması önemlidir.

19. Laravel CORS hatasını Chrome'da nasıl kontrol ederim?

Chrome Developer Tools açılarak Network sekmesinden API isteği ve özellikle OPTIONS preflight isteği incelenebilir.

20. Laravel CORS sorununu çözmek için hangi komut kullanılabilir?

Yapılandırma cache'ini temizlemek için php artisan optimize:clear kullanılabilir. Ardından API isteği tekrar test edilmelidir.

Sonuç

Laravel CORS hatası çoğu zaman frontend ile API arasındaki origin, HTTP methodu, header, credentials veya preflight yapılandırmasının uyuşmamasından kaynaklanır.

Özellikle production projelerinde yalnızca * kullanarak problemi geçici olarak kapatmak yerine hangi frontend uygulamalarının API'ye erişmesi gerektiğini belirlemek daha sağlıklı bir yapı sağlar.