[Bug]: 500 ffmpeg error in /v1/video/thumbnail and no stderr output in logs

[noubs971-stack]

Describe the bug

I'm getting a 500 error when using the /v1/video/thumbnail endpoint, but I cannot see the actual FFmpeg stderr output in the logs.

Steps to reproduce:

1. Run stephengpope/no-code-architects-toolkit:latest in Docker.
2. Send a POST request to http://127.0.0.1:8080/v1/video/thumbnail with:

   {
     "video_url": "https://www.youtube.com/watch?v=9bZkp7q19f0"
   }

NCA returns:{
"code": 500,
"endpoint": "/v1/video/thumbnail",
"message": "ffmpeg error (see stderr output for detail)",
"run_time": X.XXX
}
In docker logs nca-toolkit, I only see:
ERROR:routes.v1.video.thumbnail:Job xxx: Error during thumbnail extraction - ffmpeg error (see stderr output for detail)
→ the actual FFmpeg stderr is not visible.

Expected:

Either a proper thumbnail,

or the real FFmpeg error in the logs so we can debug it.

Question:

Can you expose the FFmpeg stderr output in the logs, or add an option to enable verbose FFmpeg logging?Additional info:Used Docker image: stephengpope/no-code-architects-toolkit:latest

Test URL: https://www.youtube.com/watch?v=9bZkp7q19f0

Reproduction Steps

1. Lancer le conteneur Docker du NCA Toolkit :
   docker run -d -p 8080:8080
   -e API_KEY=youtube2024
   stephengpope/no-code-architects-toolkit:latest

2. Envoyer une requête POST vers l’endpoint /v1/video/thumbnail, par exemple avec curl :
   curl -X POST http://127.0.0.1:8080/v1/video/thumbnail
   -H "X-API-Key: youtube2024"
   -H "Content-Type: application/json"
   -d "{"video_url":"https://www.youtube.com/watch?v=9bZkp7q19f0\"}"

3. L’API renvoie :
   {
   "code": 500,
   "endpoint": "/v1/video/thumbnail",
   "message": "ffmpeg error (see stderr output for detail)"
   }

4. Dans docker logs nca-toolkit, on voit seulement :
   ERROR:routes.v1.video.thumbnail:Job xxx: Error during thumbnail extraction - ffmpeg error (see stderr output for detail)
   → le message FFmpeg réel (stderr) n’apparaît pas dans les logs.

Expected behavior

Comportement attendu :

• Si la vidéo que j'envoie à l'endpoint /v1/video/thumbnail est valide, l'API devrait soit :

  • renvoyer un code 200 et un JSON avec le chemin du thumbnail généré,
  • soit renvoyer une erreur détaillée (par exemple 400 ou 422) avec un message clair sur le type de problème (URL invalide, format non supporté, etc.).

• Si l'erreur vient de FFmpeg (problème de format, de codec, de timeout, etc.), le message FFmpeg réel (stderr) devrait apparaître dans les logs Docker du conteneur NCA, ou au moins être inclus dans le champ "message" ou "response" de la réponse JSON, pour qu'on puisse comprendre ce qui se passe et adapter nos vidéos ou notre configuration.

Screenshots and relevant files

Captures d’écrans et fichiers pertinents :

• Capture de l’erreur retournée par l’API NCA dans n8n (ou via curl) :

  • Écran du node HTTP Request n8n montrant la requête vers /v1/video/thumbnail.
  • Écran du JSON de réponse avec "code": 500 et "message": "ffmpeg error (see stderr output for detail)".

• Capture des logs Docker :

  • Capture de la console de docker logs nca-toolkit montrant la ligne :
    ERROR:routes.v1.video.thumbnail:Job xxx: Error during thumbnail extraction - ffmpeg error (see stderr output for detail)
  • Importance : le message FFmpeg réel (stderr) n’apparaît pas, ce qui rend le debug très difficile.

• (Optionnel) Capture de la configuration du conteneur Docker :

  • docker inspect nca-toolkit (ou la ligne de commande docker run utilisée).

Platform

Local

Would you like to work on this issue?

None

Checklist

• I have searched the open issues for duplicates.
• I have shown the entire traceback, if possible.

Additional Context

Contexte supplémentaire :

• J’utilise le toolkit NCA via Docker en local, relié à n8n.
• Le problème se produit systématiquement avec différentes vidéos YouTube (simples comme complexes), donc ce n’est pas lié à un seul format ou à une seule URL.
• Le conteneur NCA répond normalement sur d’autres endpoints (par exemple /authenticate) ; le bug semble spécifique à /v1/video/thumbnail + FFmpeg.
• J’aimerais que le message FFmpeg (stderr) apparaisse dans le JSON ou dans les logs Docker pour mieux comprendre l’erreur et adapter mes vidéos ou ma configuration.

[noubs971-stack]

Hello, thank you for reviewing this bug.

I am running NCA via Docker locally and calling it from n8n.
The endpoint /authenticate works fine, so the issue seems specific to /v1/video/thumbnail + FFmpeg.

When I call /v1/video/thumbnail with a YouTube URL (any simple video), the API returns a 500 error with "ffmpeg error (see stderr output for detail)".
However, the real FFmpeg stderr is not printed in the JSON response nor in the Docker logs (docker logs nca-toolkit), which makes debugging very hard.

My expectation is that the actual FFmpeg error message (stderr) should be visible either:

• inside the JSON response (in message or a dedicated ffmpeg_error field), or
• in the Docker logs.

That way we can understand exactly what failed (unsupported format, codec issue, timeout, etc.) and adapt our videos or configuration accordingly.

[noubs971-stack]

Hello, thank you for reviewing this bug.

I am running NCA via Docker locally and calling it from n8n.
The endpoint /authenticate works fine, so the issue seems specific to /v1/video/thumbnail + FFmpeg.

When I call /v1/video/thumbnail with a YouTube URL, the API returns a 500 error with "ffmpeg error (see stderr output for detail)".
However, the real FFmpeg stderr is not shown in the JSON nor in the Docker logs (docker logs nca-toolkit), so it's hard to debug.

My expectation is that the actual FFmpeg error (stderr) should be exposed either in the JSON response or in the Docker logs so we can understand what failed (unsupported format, codec, timeout, etc.).

[noubs971-stack]

Follow-up & Technical Summary

Hi @stephengpope 👋

I'd like to provide a more detailed technical recap to help diagnose and fix this issue, in case it's useful for you or any contributor.

---

Root Cause Analysis (suspected)

After investigation, the /v1/video/thumbnail endpoint fails with a generic 500 - ffmpeg error (see stderr output for detail) message, but the actual FFmpeg stderr is swallowed and never surfaced — neither in the JSON response nor in Docker logs.

The likely root cause is in the exception handling of the thumbnail route: when subprocess.run() (or equivalent) calls FFmpeg and it fails, the stderr output is captured but not logged or forwarded to the HTTP response.

---

What was tested

• Docker image: stephengpope/no-code-architects-toolkit:latest
• Endpoint: POST /v1/video/thumbnail
• Payload: { "video_url": "https://www.youtube.com/watch?v=9bZkp7q19f0" }
• Other endpoints (e.g. /authenticate) work fine → issue is specific to this endpoint + FFmpeg subprocess
• Tested with multiple YouTube URLs (simple & complex) → always 500, no stderr visible

---

Suggested Fix

In the thumbnail route handler (likely routes/v1/video/thumbnail.py or similar), wherever FFmpeg is called via subprocess, the fix would be to:

1. Capture stderr explicitly: use stderr=subprocess.PIPE in the subprocess.run() call
2. Log the stderr: add logger.error(f"FFmpeg stderr: {result.stderr.decode()}") when the return code is non-zero
3. Optionally expose it in the JSON response: include "ffmpeg_stderr": result.stderr.decode() in the error response body

Example patch:

result = subprocess.run(
    ffmpeg_cmd,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE  # <- make sure this is set
)
if result.returncode != 0:
    stderr_output = result.stderr.decode("utf-8", errors="replace")
    logger.error(f"Job {job_id}: FFmpeg stderr: {stderr_output}")
    raise Exception(f"ffmpeg error: {stderr_output}")

---

Why this matters

Without the real FFmpeg error message, users integrating NCA into automation tools (like n8n) have no way to debug what went wrong — whether it's an unsupported format, a codec issue, a network timeout downloading the video, or a permission error.

Exposing the stderr either in logs or in the JSON response (even just "message": f"ffmpeg error: {stderr_output}") would make a huge difference for debugging.

---

Thank you for maintaining this great toolkit! Happy to test a fix or submit a PR if that would help. 🙏