digiserver-v2/old_code_documentation/EDIT_MEDIA_TROUBLESHOOTING.md

Edit Media API Troubleshooting Guide

Issue

Players are trying to send edited images to the server via the edit image API, but nothing is happening on the server.

Diagnosis Performed

1. API Endpoint Status ✅

• Endpoint: POST /api/player-edit-media
• Status: Exists and properly implemented
• Location: app/blueprints/api.py (lines 711-851)
• Authentication: Requires Bearer token with valid player auth code

2. Bug Found and Fixed 🐛

Found undefined variable bug in the receive_edited_media() function:

• Issue: playlist variable was only defined inside an if block
• Problem: When a player has no assigned playlist, the variable remained undefined
• Error: Would cause UnboundLocalError when trying to return the response
• Fix: Initialize playlist = None before the conditional block
• Commit: 8a89df3

3. Server Logs Check ✅

• No player-edit-media requests found in recent logs
• Conclusion: Requests are not reaching the server, indicating a client-side issue

Possible Root Causes

A. Player App Not Sending Requests

The player application might not be calling the edit media endpoint. Check:

• Is the "edit on player" feature enabled for the content?
• Does the player app have code to capture edited images?
• Are there errors in the player app logs?

B. Wrong Endpoint URL

If the player app is hardcoded with an incorrect URL, requests won't reach the server.

• Expected URL: {server_url}/api/player-edit-media
• Required Header: Authorization: Bearer {player_auth_code}

C. Network Issues

• Firewall blocking requests
• Network connectivity issues between player and server
• SSL/HTTPS certificate validation failures

D. Request Format Issues

The endpoint expects:

Content-Type: multipart/form-data
- image_file: The edited image file (binary)
- metadata: JSON string with this structure:
  {
    "time_of_modification": "2026-01-17T19:50:00Z",
    "original_name": "image.jpg",
    "new_name": "image_v1.jpg",
    "version": 1,
    "user_card_data": "optional_user_code"
  }

E. Authentication Issues

• Player's auth code might be invalid
• Bearer token not being sent correctly
• Auth code might have changed

Testing Steps

1. Verify Endpoint is Accessible

curl -X POST http://localhost:5000/api/player-edit-media \
  -H "Authorization: Bearer <valid_player_auth_code>" \
  -F "image_file=@test.jpg" \
  -F "metadata={\"time_of_modification\":\"2026-01-17T20:00:00Z\",\"original_name\":\"4k1.jpg\",\"new_name\":\"4k1_v1.jpg\",\"version\":1}"

2. Check Player Logs

Look for errors in the player application logs when attempting to send edits

3. Monitor Server Logs

Enable debug logging and watch for:

docker compose logs digiserver-app -f | grep -i "edit\|player-edit"

4. Verify Player Has Valid Auth Code

curl -X POST http://localhost:5000/api/auth/verify \
  -H "Authorization: Bearer <player_auth_code>" \
  -H "Content-Type: application/json"

Server API Response

Success Response (200 OK)

{
  "success": true,
  "message": "Edited media received and processed",
  "edit_id": 123,
  "version": 1,
  "old_filename": "image.jpg",
  "new_filename": "image_v1.jpg",
  "new_playlist_version": 34
}

Error Responses

• 401: Missing or invalid authorization header
• 403: Invalid authentication code
• 400: Missing required fields (image_file, metadata, etc.)
• 404: Original content file not found in system
• 500: Internal server error (check logs)

Expected Server Behavior

When an edit is successfully received:

1. ✅ File is saved to /static/uploads/edited_media/<content_id>/<filename>
2. ✅ Metadata JSON is saved alongside the file
3. ✅ PlayerEdit record is created in database
4. ✅ PlayerUser record is auto-created if user_card_data provided
5. ✅ Playlist version is incremented (if player has assigned playlist)
6. ✅ Playlist cache is cleared
7. ✅ Action is logged in server_log table

Database Records

After successful upload, check:

-- Player edit records
SELECT * FROM player_edit WHERE player_id = ? ORDER BY created_at DESC;

-- Verify file exists
ls -la app/static/uploads/edited_media/

-- Check server logs
SELECT * FROM server_log WHERE action LIKE '%edited%' ORDER BY created_at DESC;

Next Steps

1. Check if player app is configured with correct server URL
2. Verify player has "edit on player" enabled for the content
3. Check player app logs for any error messages
4. Test endpoint connectivity using curl/Postman
5. Monitor server logs while player attempts to send an edit
6. Verify player's auth code is valid and unchanged