---
title: Media Pipeline Pitfalls
created: '2026-05-23'
updated: '2026-05-27'
type: tech
namespace: family
tags: [media-pipeline, pitfalls, torrents, infra]
related:
  - "[[tech/arr-stack-kraken]]"
  - "[[concepts/watchlist-automation]]"
---

# Media Pipeline Pitfalls

## Torrents — Do Not Rename Files

Never rename torrent source files or folders while a torrent is active.
Transmission tracks files by path. Renaming breaks the association and
causes re-download or stalled seeding.

Правильный порядок (когда файл уже лежит в нужном месте, но с другим кейсом):
1. Переименовать файл/папку на диске (Linux ext4 case-sensitive)
2. Вызвать `torrent-set-location` с новым путём + `move=false`
3. Запустить торрент на сидирование

## torrent-set-location Updates downloadDir

`torrent-set-location` in the Transmission RPC updates `downloadDir` in
the torrent metadata. Use this when moving completed files, not a manual
rename. Sequence:

1. Move files to new location on disk
2. Call `torrent-set-location` with the new path + `move=false`
3. Verify torrent goes back to seeding state

## Router Creates Subdirectories — Transmission downloadDir Stale

`router.py` creates subdirectory per title under the genre folder
(lowercase name, e.g. `/media/cartoons/бобик в гостях у барбоса/`).
Transmission still holds the old `downloadDir` pointing to the parent
(`/media/cartoons/`). Result: torrents show "No data found" error.

Fix:
1. Find the actual subdirectory on disk
2. Call `torrent-set-location` with the subdirectory path + `move=false`
3. Transmission verifies and resumes seeding

## Alpine Container — No Docker-in-Docker

`on-download-complete.sh` runs inside the Transmission Alpine container.
Docker CLI is not available there — using `docker run` inside the container
fails silently or errors. Python 3.14 IS available in the Alpine image.

Solution: `sync.py` (Python3, ~190 lines) in the same container:
- Reads `config.json` for sorting rules + credentials (same file as linker container)
- Queries TMDB for genre routing
- Creates hardlinks + calls Transmission RPC `torrent-set-location`
Location: `/srv/.../docker/media-pipeline/sync.py`

## Transmission download-dir — без /complete

download-dir: `/downloads` (не `/downloads/complete`).
incomplete-dir: `/downloads/incomplete` (enabled).

Менять через остановку Transmission → правка `settings.json` → запуск.

## media-router.sh — Telegram-уведомления

Скрипт-обёртка над `router.py`. Запускается из crontab каждые 10 минут.
- При `Nothing to do` — SILENT
- При активности — отправляет отчёт в Telegram Kraken (kraken_htpc_bot)
- `BOT_TOKEN` и `CHAT_ID` хардкодом в скрипте

## Удаление дубликатов из downloads/complete

После перемещения файлов в `/media/{movies,cartoons,series,...}/`:
1. Проверить, что файлы в movies — **реальные** (-rwx), не symlink'и
2. Проверить что inode разные (это копии, не один файл)
3. Удалить из `downloads/complete/`
4. Обновить путь в Transmission

## General Rules

- Never touch source files/folders (media-pipeline USER.md rule)
- `resolve-manual` is emergency-only
- NFO files: do not create manually; let the pipeline handle them
- Never delete test files from the pipeline project