플러그인 업데이트 후 WordPress 500 오류

이 오류의 의미와 확인 방법

• 플러그인을 업데이트하기 전에는 사이트가 정상적으로 작동했지만, 이후 프런트엔드, WordPress 대시보드 또는 둘 다 HTTP 500 오류를 반환하기 시작합니다.
• 수동 또는 자동 플러그인 업데이트 직후 문제가 발생할 수 있습니다.
• 공개 사이트는 로드되지만 /wp-admin/만 실패하거나, 업데이트된 플러그인을 사용하는 페이지와 요청만 실패할 수 있습니다.
• 브라우저에는 근본 원인 대신 일반적인 “500 Internal Server Error”, 빈 페이지 또는 WordPress 치명적 오류 메시지가 표시될 수 있습니다.
• 최근 업데이트된 플러그인 디렉터리의 이름을 변경하면 사이트가 다시 로드될 수 있습니다.
• 서버 또는 WordPress 디버그 로그에 PHP 치명적 오류, 구문 분석 오류, 파일 누락 오류 또는 업데이트된 플러그인을 지칭하는 메시지가 포함될 수 있습니다.

가능성이 높은 순서의 주요 원인

1. PHP 비호환성: 새 플러그인 버전에서 서버가 제공하지 않는 PHP 기능이나 버전을 요구할 수 있습니다.
2. 플러그인, 테마 또는 WordPress 충돌: 업데이트가 다른 확장 기능, 활성 테마 또는 설치된 WordPress 코어 버전과 제대로 동작하지 않을 수 있습니다. 중복 함수 또는 클래스 선언은 흔한 단서입니다.
3. 불완전하거나 손상된 업데이트: 시간 초과, 연결 중단 또는 파일 전송 실패로 인해 플러그인 파일이 누락되거나 손상될 수 있습니다.
4. 플러그인 회귀 문제: 새 릴리스에 명시된 PHP 및 WordPress 요구 사항을 충족하더라도 해당 사이트의 구성에 영향을 주는 결함이 포함될 수 있습니다.
5. 별도의 광범위한 호스팅 문제: 업데이트된 플러그인을 비활성화해도 아무런 변화가 없다면 500 응답은 다른 최근 변경 사항, PHP 구성, 권한, 리소스 제한 또는 서버 수준의 장애와 관련되었을 수 있습니다.

해결 방법

1. 발생 시점과 영향 범위 확인

오류가 발생하기 직전에 업데이트된 플러그인을 확인하세요. 여러 플러그인을 함께 업데이트했다면 모두 기록하세요. 공개 사이트, /wp-admin/ 및 오류가 발생하는 플러그인 관련 기능을 확인하세요. 의심되는 원인을 테스트하기 전까지는 관련 없는 업데이트를 진행하지 마세요.

2. 대시보드를 사용하지 않고 업데이트된 플러그인 비활성화

파일을 변경하기 전에 SFTP 또는 호스팅 파일 관리자를 통해 사이트에 권한을 부여받은 상태로 접근할 수 있는지 확인하고, 가능하면 최신 백업을 준비하세요. wp-content/plugins/를 열고 의심되는 플러그인 디렉터리 이름에 -disabled 같은 접미사를 추가하여 변경하세요.

프런트엔드와 /wp-admin/을 새로고침하세요.

• 사이트가 복구되면 로그를 확인하고 롤백 또는 호환성 수정 방법을 결정하는 동안 플러그인을 비활성화된 상태로 유지하세요.
• 아무런 변화가 없다면 원래 디렉터리 이름으로 되돌린 후 같은 시점에 업데이트된 다음 플러그인을 테스트하세요.
• 최근 업데이트된 모든 플러그인을 비활성화한 후에도 오류가 계속되면 서버 및 PHP 로그를 확인하고 최근의 다른 호스팅 또는 구성 변경 사항을 검토하세요.

디렉터리 이름을 변경하면 WordPress가 로드하는 플러그인이 바뀌므로, 이를 근본적인 문제를 파악하고 수정하는 대신 사용해서는 안 됩니다.

3. 근본적인 PHP 오류 확인

500 응답은 외부로 나타난 증상일 뿐입니다. wp-config.php를 편집할 권한이 있다면 편집이 중지되었음을 나타내는 줄 위에서 일시적으로 로깅을 활성화하세요.

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

의심되는 플러그인은 계속 비활성화된 상태로 두고, 필요한 경우 현재 로그를 보존하세요. 오류를 재현할 준비가 되었을 때만 플러그인을 다시 활성화한 다음 한 번 재현하고 wp-content/debug.log 및 호스팅 패널의 PHP 또는 서버 오류 로그를 확인하세요. 플러그인 이름, PHP 버전 관련 메시지, 누락된 파일, 구문 분석 오류, Cannot redeclare function 또는 Cannot declare class를 찾으세요.

디버그 로깅에는 민감한 구현 세부 정보가 기록될 수 있으므로 일시적으로만 사용해야 합니다. 테스트가 끝나면 설정을 비활성화하세요. 특히 공개 운영 사이트에서는 반드시 비활성화하고, 호스팅 절차에 따라 노출된 로그 데이터를 삭제하거나 안전하게 보호하세요.

4. 로그 메시지를 가능한 원인과 대조

• 지원되지 않는 PHP 기능 또는 필요한 PHP 버전에 관한 메시지는 PHP 호환성 문제를 나타냅니다.
• Cannot redeclare function 또는 Cannot declare class와 함께 두 확장 기능이나 테마의 이름이 표시되면 호환성 충돌을 의미합니다.
• 최근 업데이트된 플러그인 디렉터리에서 누락된 파일, 구문 분석 오류 또는 오류가 발견되면 불완전하거나 손상된 업데이트일 가능성이 있습니다.
• WordPress 코어 또는 다른 확장 기능의 이름이 표시되는 오류는 업데이트로 인해 더 광범위한 호환성 문제가 드러났음을 의미할 수 있습니다.
• 로그에 플러그인이나 관련 구성 요소가 표시되지 않는다면 업데이트가 원인이라고 단정하기 전에 호스팅 수준의 오류를 확인하세요.

5. 마지막으로 정상 작동한 플러그인 버전으로 롤백

사이트를 신속하게 복구해야 한다면 현재 플러그인 파일의 복사본을 보존하고, 확인된 백업 또는 플러그인의 공식 배포 경로에서 제공하는 이전 패키지를 사용하세요. SFTP 또는 호스팅 파일 관리자를 통해 해당 파일을 업로드하거나 복원한 다음 플러그인을 다시 활성화하기 전에 사이트를 테스트하세요.

정상 작동하는 백업의 유일한 복사본을 덮어쓰지 마세요. 원인을 파악하고 호환되는 릴리스가 제공될 때까지 이 플러그인의 자동 업데이트를 비활성화하거나 검토 후 업데이트하도록 설정하세요.

6. PHP 및 WordPress 요구 사항 확인

업데이트된 플러그인 릴리스에 명시된 최소 PHP 및 WordPress 버전과 사이트의 실제 버전을 비교하세요. 대시보드에 접근할 수 있다면 PHP 정보는 일반적으로 도구 → 사이트 건강 상태 → 정보에서 확인할 수 있으며, 호스팅 제어판에도 현재 PHP 버전이 표시될 수 있습니다.

PHP 또는 WordPress 버전이 플러그인 요구 사항보다 낮다면 백업을 생성하고 업그레이드하기 전에 테마, 다른 플러그인 및 호스팅 환경과의 호환성을 확인하세요. 호스트가 PHP를 관리한다면 지원되는 업그레이드 경로를 호스트에 문의하세요. 운영 환경의 PHP 버전을 무작정 변경하지 마세요. 사이트의 다른 부분에 영향을 줄 수 있습니다.

7. 확인된 충돌 또는 회귀 문제 에스컬레이션

호환되지 않는 업데이트를 비활성화된 상태로 유지하거나 마지막으로 정상 작동한 버전으로 복원한 후, 정확한 치명적 오류, 플러그인 버전, PHP 버전, WordPress 버전 및 재현 단계를 해당 플러그인 또는 테마 개발자에게 전달하세요. 플러그인 파일을 영구적으로 직접 수정하지 마세요. 향후 업데이트에서 변경 사항이 덮어써질 수 있으며 사이트가 지원되지 않는 상태로 남을 수 있습니다.

예방 및 해결 확인 방법

• 플러그인을 업데이트하기 전에 데이터베이스와 사이트 파일을 모두 백업하고 백업이 정상인지 확인하세요.
• 가능하면 플러그인을 한 번에 하나씩 업데이트하여 문제가 특정 변경 사항과 연관되는지 확인하세요.
• 중요한 플러그인, WordPress 및 PHP 변경 사항은 운영 환경에 적용하기 전에 스테이징 복사본에서 테스트하세요.
• PHP와 WordPress를 플러그인 및 테마에 명시된 지원 범위 내에서 유지하세요.
• 업데이트할 때마다 공개 사이트, /wp-admin/, 로그인, 폼 및 업데이트된 플러그인이 제공하는 기능을 테스트하세요.
• 비즈니스에 중요한 플러그인이나 호환성 문제가 발생한 이력이 있는 플러그인의 자동 업데이트를 검토하세요.
• 문서화된 마지막 정상 작동 플러그인 버전과 복구 방법을 준비해 두세요.
• 문제 해결이 끝나면 임시 디버그 표시 및 로깅 설정을 비활성화하고, 내부 오류 세부 정보가 포함된 로그를 보호하거나 삭제하세요.

자주 묻는 질문