ATH-MaaS/Pixelle-Video · error · HTTPException

str(e)

Error message

str(e)

What it means

The frame render endpoint wraps template rendering in a broad except that converts any exception into HTTP 500 with str(e) as detail. Any unhandled failure in rendering — unknown template name, bad parameters, media/asset loading errors — surfaces as this opaque 500.

Source

Thrown at api/routers/frame.py:83

        # Create HTML frame generator
        generator = HTMLFrameGenerator(template_path)
        
        # Generate frame
        frame_path = await generator.generate_frame(
            title=request.title,
            text=request.text,
            image=request.image
        )
        
        return FrameRenderResponse(
            frame_path=frame_path,
            width=width,
            height=height
        )
        
    except Exception as e:
        logger.error(f"Frame render error: {e}")
        raise HTTPException(status_code=500, detail=str(e))


@router.get("/template/params", response_model=TemplateParamsResponse)
async def get_template_params(
    template: str
):
    """
    Get custom parameters for a template
    
    Returns the custom parameters defined in the template HTML file.
    These parameters can be passed via `template_params` in video generation requests.
    
    Template parameters are defined using syntax: `{{param_name:type=default}}`
    
    Supported types:
    - `text`: String input
    - `number`: Numeric input
    - `color`: Color picker (hex format)

View on GitHub (pinned to 848b054e4f)

Solutions

  1. Check the server log 'Frame render error: ...' for the underlying exception.
  2. Validate the template name via the /template/params endpoint before rendering.
  3. Confirm all template parameters and media paths in the request are correct and files exist.
  4. Retry if the log indicates a transient IO/network issue.
  5. Log the traceback server-side and return a generic 500 detail to clients.

Example fix

// before
except Exception as e:
    logger.error(f"Frame render error: {e}")
    raise HTTPException(status_code=500, detail=str(e))
// after
except Exception:
    logger.exception("Frame render error")
    raise HTTPException(status_code=500, detail="Frame render failed")
Defensive patterns

Strategy: validation

Validate before calling

const paramsRes = await fetch(`/api/frame/template/params?template=${encodeURIComponent(template)}`);
if (!paramsRes.ok) throw new Error(`Template ${template} is not available (status ${paramsRes.status})`);
const params = await paramsRes.json();
// validate render request width/height and required params against `params` before calling render

Try / catch

try {
  const res = await fetch('/api/frame/render', { method: 'POST', headers: {'Content-Type':'application/json'}, body: JSON.stringify(renderRequest) });
  if (!res.ok) throw new Error(`Frame render failed (${res.status}): ${(await res.json()).detail}`);
  return await res.json();
} catch (err) {
  logger.error('Frame render request failed', err);
  throw err;
}

Prevention

When it happens

Trigger: POST to the frame render endpoint when the renderer raises: template file missing or unparseable, invalid width/height or template params, missing media asset referenced by the template, or an internal error in the rendering library.

Common situations: Misspelled template name passed in the request; template params not matching the template schema after an update; referenced media file absent from output/; renderer dependency upgraded with breaking changes.

Related errors

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