본문 바로가기
카테고리 없음

Laravel 'Route not defined' 오류 및 해결법

by blogfine 2025. 2. 26.

Laravel에서 'Route not defined' 오류란?

Laravel에서 'Route not defined' 오류는 라우트(Route)를 호출할 때, 해당 라우트가 정의되지 않았거나 잘못 정의된 경우 발생하는 오류입니다. 이 오류는 주로 route() 헬퍼 함수나 url 등의 라우트 관련 메서드를 사용했을 때 나타나며, 정의되지 않은 라우트를 참조하려고 할 때 발생합니다. 이 글에서는 Laravel에서 'Route not defined' 오류의 원인과 해결 방법에 대해 자세히 알아보겠습니다.

'Route not defined' 오류의 주요 원인

'Route not defined' 오류는 다양한 원인으로 발생할 수 있습니다. 가장 흔한 원인들은 다음과 같습니다:

  • 라우트 이름이 잘못 지정된 경우: route() 헬퍼 함수에 전달한 라우트 이름이 올바르지 않은 경우입니다.
  • 라우트 캐시 문제: 라우트를 수정한 후, 라우트 캐시가 갱신되지 않아 발생하는 문제입니다.
  • 라우트 파일에서 라우트 미등록: web.php나 api.php와 같은 라우트 파일에서 해당 라우트를 정의하지 않은 경우입니다.
  • 네임스페이스 오류: 라우트 그룹의 네임스페이스가 잘못 지정되어 라우트를 찾지 못하는 경우입니다.

1. 라우트 이름 확인

Laravel에서 'Route not defined' 오류가 발생하는 가장 일반적인 원인 중 하나는 route() 헬퍼 함수에 전달된 라우트 이름이 잘못된 경우입니다. 예를 들어, 라우트 이름을 잘못 입력했을 경우 다음과 같은 오류가 발생할 수 있습니다:

Route [nonexistent.route] not defined.

이 오류를 해결하려면, 라우트 이름이 올바르게 지정되었는지 확인해야 합니다. 아래는 라우트 이름을 정의하고 사용하는 예시입니다:

// routes/web.php

Route::get('/home', [HomeController::class, 'index'])->name('home');

// 사용 예시
홈페이지로 이동

위 코드에서는 `/home` 경로에 대한 라우트를 정의하고, 해당 라우트에 `home`이라는 이름을 부여했습니다. 이를 `route()` 헬퍼 함수로 호출할 때, 정확한 라우트 이름을 전달해야 합니다.

2. 라우트 캐시 클리어

Laravel은 라우트 캐시를 사용하여 성능을 최적화합니다. 그러나 라우트를 수정한 후, 캐시가 갱신되지 않으면 'Route not defined' 오류가 발생할 수 있습니다. 이를 해결하려면 라우트 캐시를 클리어해야 합니다.

라우트 캐시를 클리어하려면, 다음 명령어를 실행합니다:

php artisan route:clear

이 명령어는 모든 라우트 캐시를 삭제합니다. 캐시를 삭제한 후, 라우트 캐시를 다시 생성하려면 다음 명령어를 실행합니다:

php artisan route:cache

이 명령어는 라우트 캐시를 새로 생성하여 성능을 최적화할 수 있도록 합니다.

3. 라우트 파일에서 라우트 미등록

Laravel에서는 라우트를 정의하는 파일이 여러 개 있을 수 있습니다. 가장 일반적인 파일은 routes/web.php와 routes/api.php입니다. 만약 해당 라우트가 이 파일들에 등록되지 않았다면, 'Route not defined' 오류가 발생합니다.

예를 들어, 웹 애플리케이션에서 `/home` 경로에 대한 라우트가 등록되지 않은 경우, 해당 라우트를 호출할 때 오류가 발생할 수 있습니다. 이를 해결하려면 해당 라우트가 적절한 파일에 등록되어 있는지 확인하세요.

// routes/web.php
Route::get('/home', [HomeController::class, 'index'])->name('home');

위와 같이 라우트를 정의한 후, `route()` 헬퍼 함수에서 올바른 이름을 사용하여 라우트를 호출해야 합니다.

4. 라우트 네임스페이스 확인

Laravel에서 라우트를 정의할 때, 라우트 그룹에 네임스페이스를 지정할 수 있습니다. 만약 라우트 네임스페이스가 잘못 지정되면, 'Route not defined' 오류가 발생할 수 있습니다. 네임스페이스 설정을 확인하려면, 라우트 그룹에 지정된 네임스페이스가 올바른지 점검해야 합니다.

다음은 라우트 그룹의 네임스페이스를 설정하는 예시입니다:

// routes/web.php
Route::namespace('Admin')->group(function () {
    Route::get('/admin', [AdminController::class, 'index'])->name('admin.dashboard');
});

위 코드에서, 라우트 그룹에 'Admin' 네임스페이스를 지정한 후, 해당 네임스페이스에 속하는 라우트를 정의하고 있습니다. 만약 잘못된 네임스페이스를 사용하면 'Route not defined' 오류가 발생할 수 있습니다.

5. 라우트 파일 새로 고침

라우트를 새로 추가하거나 수정한 후, Laravel에서 라우트를 캐시하고 있는 경우, 새로 추가된 라우트가 반영되지 않을 수 있습니다. 이 경우, Laravel의 캐시를 새로 고쳐야 합니다. 다음 명령어를 사용하여 라우트 캐시를 새로 고칩니다:

php artisan route:cache

이 명령어는 라우트 캐시를 새로 생성하여 새롭게 추가된 라우트를 반영합니다. 캐시된 라우트를 다시 로드하려면 이 명령어를 실행하세요.

결론

'Route not defined' 오류는 라우트 이름이 잘못 지정되었거나, 라우트 캐시가 갱신되지 않거나, 라우트가 정의되지 않은 경우에 발생하는 오류입니다. 이 오류를 해결하려면 라우트 이름을 정확히 확인하고, 캐시를 클리어한 후 라우트를 새로 고쳐야 합니다. 또한, 라우트를 정의한 파일에서 해당 라우트가 올바르게 등록되어 있는지 확인하고, 라우트 네임스페이스와 설정이 정확한지 점검해야 합니다. 위의 방법들을 통해 'Route not defined' 오류를 해결하고 Laravel 애플리케이션을 원활하게 운영할 수 있습니다.

티스토리툴바