ATH-MaaS/Pixelle-Video · error · HTTPException

Template not found: {template}

Error message

Template not found: {template}

What it means

The GET /template/params endpoint maps FileNotFoundError from the template loader to HTTP 404 with 'Template not found: {template}'. It means the requested template name does not correspond to any template file the server can locate.

Source

Thrown at api/routers/frame.py:157

        logger.info(f"Get template params: {template}")
        
        # Resolve template path
        template_path = resolve_template_path(template)
        
        # Create generator and parse parameters
        generator = HTMLFrameGenerator(template_path)
        params = generator.parse_template_parameters()
        media_width, media_height = generator.get_media_size()
        
        return TemplateParamsResponse(
            template=template,
            media_width=media_width,
            media_height=media_height,
            params=params
        )
        
    except FileNotFoundError:
        raise HTTPException(status_code=404, detail=f"Template not found: {template}")
    except Exception as e:
        logger.error(f"Get template params error: {e}")
        raise HTTPException(status_code=500, detail=str(e))

View on GitHub (pinned to 848b054e4f)

Solutions

1. Check the exact template name spelling and case against available templates.
2. Confirm the template file exists in the server's template directory (list templates if an endpoint/file listing is available).
3. If custom, copy the template into the deployed server's template path / image.
4. Query /template/params for a known-good template first to verify the loader works.
5. Update client code to use the current template names after server upgrades.

Example fix

// before
await fetch(`/api/frame/template/params?template=TitleCard`); // 404: wrong name
// after
await fetch(`/api/frame/template/params?template=title_card`); // matches on-disk name

const KNOWN_TEMPLATES = ['title_card', 'lower_third', 'end_screen']; // keep in sync with server template dir
if (!KNOWN_TEMPLATES.includes(template)) throw new Error(`Unknown template: ${template}`);
const res = await fetch(`/api/frame/template/params?template=${encodeURIComponent(template)}`);
if (res.status === 404) throw new Error(`Template not deployed on server: ${template}`);

try {
  const res = await fetch(`/api/frame/template/params?template=${encodeURIComponent(template)}`);
  if (res.status === 404) throw new Error(`Template not found: ${template}`);
  if (!res.ok) throw new Error(`Template params fetch failed: ${res.status}`);
  return await res.json();
} catch (err) {
  logger.error('Template params fetch failed', err);
  throw err;
}

When it happens

Trigger: GET /template/params?template={name} where the template file for that name does not exist on disk — misspelled template name, template not deployed/installed, case mismatch, or template stored in a directory the loader does not search.

Common situations: Template names renamed in a newer server version while clients still send the old name; custom templates not copied into the server's template directory (especially in Docker images); case-sensitive filesystem mismatch between dev (macOS) and prod (Linux).

Related errors

• Template not found: {size}/{template_name} Available sizes:
• File not found: {file_path}
• Task {task_id} not found
• API VLM analysis requires an explicitly selected VLM model.
• ARK_API_KEY not set. Configure ARK only when using Seedream

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