ATH-MaaS/Pixelle-Video · error · FileNotFoundError

Template not found: {template_path}

Error message

Template not found: {template_path}

What it means

FrameHtmlRenderer._load_template raises FileNotFoundError when the HTML template file passed to the renderer does not exist on disk. It is thrown eagerly in __init__, so constructing the renderer with a bad template path fails immediately, before any rendering work. This guards against silently producing frames from missing templates.

Source

Thrown at pixelle_video/services/frame_html.py:118

                    "No fonts detected by fontconfig. "
                    "Install fonts with: sudo apt-get install -y fonts-liberation fonts-noto-cjk"
                )
            else:
                logger.debug(f"Fontconfig detected {len(result.stdout.splitlines())} fonts")
                
        except FileNotFoundError:
            logger.warning(
                "fontconfig (fc-list) not found on system. "
                "Install with: sudo apt-get install -y fontconfig"
            )
        except Exception as e:
            logger.debug(f"Could not check fontconfig status: {e}")
    
    def _load_template(self, template_path: str) -> str:
        """Load HTML template from file"""
        path = Path(template_path)
        if not path.exists():
            raise FileNotFoundError(f"Template not found: {template_path}")
        
        with open(path, 'r', encoding='utf-8') as f:
            content = f.read()
        
        logger.debug(f"Template loaded: {len(content)} chars")
        return content
    
    def _parse_media_size_from_meta(self) -> tuple[Optional[int], Optional[int]]:
        """
        Parse media size from meta tags in template
        
        Looks for meta tags:
        - <meta name="template:media-width" content="1024">
        - <meta name="template:media-height" content="1024">
        
        Returns:
            Tuple of (width, height) or (None, None) if not found
        """

View on GitHub (pinned to 848b054e4f)

Solutions

1. Print and verify the template_path exists: python -c "import os; print(os.path.exists('<path>'))" and fix typos or missing files.
2. Convert the template path to an absolute path anchored at the package directory (e.g. Path(__file__).parent / 'templates' / 'frame.html') instead of relying on CWD.
3. Ensure template assets are included in packaging/deployment (MANIFEST.in / package_data / Dockerfile COPY).
4. If the template is user-supplied via config, validate the path before constructing the renderer and fall back to the built-in default template.

Example fix

// before
renderer = FrameHtmlRenderer("templates/frame.html")

// after
from pathlib import Path
template = Path(__file__).parent / "templates" / "frame.html"
if not template.exists():
    template = DEFAULT_TEMPLATE_PATH  # bundled fallback
renderer = FrameHtmlRenderer(str(template))

from pathlib import Path
def ensure_template(path: str) -> str:
    p = Path(path)
    if not p.is_file():
        raise ValueError(f"Template missing before render: {p.resolve()}")
    return str(p)

renderer = FrameHtmlRenderer(ensure_template(cfg.template_path))

try:
    renderer = FrameHtmlRenderer(template_path)
except FileNotFoundError as e:
    logger.warning("template missing (%s), using default", e)
    renderer = FrameHtmlRenderer(DEFAULT_TEMPLATE_PATH)

When it happens

Trigger: Instantiating the HTML frame renderer (FrameHtmlRenderer.__init__ -> _load_template) with a template_path whose Path.exists() is False: a typo'd filename, a template removed after packaging, a relative path resolved against a different working directory, or a style config pointing at a nonexistent custom template.

Common situations: Deploying the app without the bundled template assets; changing CWD so a relative 'templates/frame.html' no longer resolves; renaming templates in a style config (render_style_config) without updating paths; Docker images that .dockerignore the templates directory.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Generated media file not found: {local_path}
• Image file not found: {image_path}
• Video file not found: {video_path}
• 文件不存在: {file_path}
• Image file not found: {image_path}

AI-assisted analysis of ATH-MaaS/Pixelle-Video@848b054e4f (2026-08-30). Data as JSON: /api/errors/74cdc9aba3922732. Report an issue: GitHub.