Fix SuspiciousFileOperation: The joined path (/etc/passwd) is located outside of the base path component (/app/media). in Django

This error means a file upload path tried to escape the MEDIA_ROOT directory, which Django blocks as a security measure. Fix it by sanitizing uploaded filenames, using Django's FileSystemStorage which handles path traversal protection, and never constructing file paths from user input without validation.

Reading the Stack Trace

Here's what each line means:

• File "/app/uploads/views.py", line 22, in upload_document: The view passes the user-provided filename directly to storage.save without sanitizing it.
• File "/venv/lib/python3.11/site-packages/django/utils/_os.py", line 17, in safe_join: Django's safe_join detects path traversal attempts (like ../../../etc/passwd) and blocks them.
• raise SuspiciousFileOperation(: Django raises this security exception to prevent directory traversal attacks on the filesystem.

Common Causes

def upload_document(request):
    uploaded_file = request.FILES['document']
    filename = request.POST.get('filename', uploaded_file.name)
    path = default_storage.save(filename, uploaded_file)  # User controls filename
    return JsonResponse({'path': path})

def upload_document(request):
    uploaded_file = request.FILES['document']
    # No size check — user can upload a 10GB file
    path = default_storage.save(uploaded_file.name, uploaded_file)

class DocumentForm(forms.Form):
    document = forms.FileField()  # Accepts ANY file type
    # No validators for allowed extensions

The Fix

Generate a safe filename using UUID instead of accepting user input. Validate file extensions and size in the form. Django's FileExtensionValidator checks the extension, and the clean method enforces a size limit.

def upload_document(request):
    uploaded_file = request.FILES['document']
    filename = request.POST.get('filename', uploaded_file.name)
    path = default_storage.save(filename, uploaded_file)
    return JsonResponse({'path': path})

import os
import uuid
from django.core.validators import FileExtensionValidator

ALLOWED_EXTENSIONS = ['pdf', 'doc', 'docx', 'txt', 'csv']
MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB

class DocumentForm(forms.Form):
    document = forms.FileField(
        validators=[FileExtensionValidator(allowed_extensions=ALLOWED_EXTENSIONS)]
    )

    def clean_document(self):
        doc = self.cleaned_data['document']
        if doc.size > MAX_FILE_SIZE:
            raise forms.ValidationError(f'File size must be under {MAX_FILE_SIZE // (1024*1024)}MB.')
        return doc

def upload_document(request):
    form = DocumentForm(request.POST, request.FILES)
    if form.is_valid():
        uploaded_file = form.cleaned_data['document']
        ext = os.path.splitext(uploaded_file.name)[1]
        safe_name = f'documents/{uuid.uuid4().hex}{ext}'
        path = default_storage.save(safe_name, uploaded_file)
        return JsonResponse({'path': path})
    return JsonResponse({'errors': form.errors}, status=400)

Testing the Fix

import pytest
from django.test import TestCase, Client
from django.core.files.uploadedfile import SimpleUploadedFile


class TestFileUpload(TestCase):
    def setUp(self):
        self.client = Client()

    def test_valid_pdf_upload(self):
        file = SimpleUploadedFile('test.pdf', b'%PDF-1.4 content', content_type='application/pdf')
        response = self.client.post('/upload/', {'document': file})
        assert response.status_code == 200

    def test_disallowed_extension_rejected(self):
        file = SimpleUploadedFile('malware.exe', b'MZ...', content_type='application/octet-stream')
        response = self.client.post('/upload/', {'document': file})
        assert response.status_code == 400

    def test_oversized_file_rejected(self):
        large_content = b'x' * (11 * 1024 * 1024)  # 11MB
        file = SimpleUploadedFile('big.pdf', large_content, content_type='application/pdf')
        response = self.client.post('/upload/', {'document': file})
        assert response.status_code == 400

    def test_path_traversal_blocked(self):
        file = SimpleUploadedFile('../../../etc/passwd', b'root:x:0:0', content_type='text/plain')
        response = self.client.post('/upload/', {'document': file})
        # Should either reject or sanitize the filename
        assert response.status_code in (200, 400)

Run your tests:

pytest

Pushing Through CI/CD

git checkout -b fix/file-upload-security,git add uploads/views.py uploads/forms.py,git commit -m "fix: sanitize upload filenames and validate file type/size",git push origin fix/file-upload-security

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          cache: 'pip'
      - run: pip install -r requirements.txt
      - run: python manage.py check --deploy
      - run: pytest --tb=short -q

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

pip install bugstack

import bugstack

bugstack.init(api_key=os.environ["BUGSTACK_API_KEY"])

Deploying the Fix (Manual Path)

1. Run the full test suite locally including file upload security tests.
2. Open a pull request with the file validation changes.
3. Wait for CI checks to pass on the PR.
4. Have a teammate review and approve the PR.
5. Merge to main and verify file uploads work correctly in staging.

Frequently Asked Questions