Clarify what is a valid template (maybe clarify error)

@ayjayt is there anything invalid with the example code I am using here?

import kaleido
import plotly.graph_objects as go
import pathlib

fig = go.Figure(data=[go.Scatter(y=[1, 3, 2])])
kaleido.write_fig_sync(fig, path="figure.png", kopts=dict(page_generator=pathlib.Path("/Users/liamconnors/Desktop/kaleido-tests/template.html")))

Building from this branch, I couldn't get it to work. I get the following error:

ERROR	Thread(Thread-5 (run)) Task(Task-19) kaleido._kaleido_tab:_kaleido_tab.py:_calc_fig()- Raising error on f2igure.png
ERROR	Thread(Thread-5 (run)) kaleido.kaleido:kaleido.py:_check_render_task()- Render Task Error In f2igure.png- 
 Traceback (most recent call last):
   File "[/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/kaleido.py", line 273](http://localhost:8890/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/kaleido.py#line=272), in _render_task
    await asyncio.wait_for(
    ...<6 lines>...
    )
   File "[/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/asyncio/tasks.py", line 507](http://localhost:8890/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/asyncio/tasks.py#line=506), in wait_for
    return await fut
           ^^^^^^^^^
   File "[/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/_kaleido_tab.py", line 223](http://localhost:8890/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/_kaleido_tab.py#line=222), in _write_fig
    img, profile = await self._calc_fig(
                   ^^^^^^^^^^^^^^^^^^^^^
    ...<5 lines>...
    )
    ^
   File "[/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/_kaleido_tab.py", line 323](http://localhost:8890/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/_kaleido_tab.py#line=322), in _calc_fig
    raise e
 kaleido._kaleido_tab.JavascriptError: {'result': {'type': 'object', 'subtype': 'error', 'className': 'ReferenceError', 'description': 'ReferenceError: kaleido_scopes is not defined\n    at <anonymous>:1:26', 'objectId': '-8540391823105239674.1.1'}, 'exceptionDetails': {'exceptionId': 1, 'text': 'Uncaught', 'lineNumber': 0, 'columnNumber': 25, 'scriptId': '11', 'stackTrace': {'callFrames': [{'functionName': '', 'scriptId': '11', 'url': '', 'lineNumber': 0, 'columnNumber': 25}]}, 'exception': {'type': 'object', 'subtype': 'error', 'className': 'ReferenceError', 'description': 'ReferenceError: kaleido_scopes is not defined\n    at <anonymous>:1:26', 'objectId': '-8540391823105239674.1.2'}}}

ERROR	Thread(Thread-5 (run)) kaleido.kaleido:kaleido.py:_check_render_task()- Cancelling all.
ERROR	Thread(Thread-5 (run)) asyncio:base_events.py:default_exception_handler()- Exception in callback Kaleido._check_render_task()()
handle: <Handle Kaleido._check_render_task()()>
 Traceback (most recent call last):
   File "[/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/asyncio/events.py", line 89](http://localhost:8890/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/asyncio/events.py#line=88), in _run
    self._context.run(self._callback, *self._args)
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   File "[/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/kaleido.py", line 263](http://localhost:8890/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/kaleido.py#line=262), in _check_render_task
    raise e
   File "[/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/kaleido.py", line 273](http://localhost:8890/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/kaleido.py#line=272), in _render_task
    await asyncio.wait_for(
    ...<6 lines>...
    )
   File "[/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/asyncio/tasks.py", line 507](http://localhost:8890/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/asyncio/tasks.py#line=506), in wait_for
    return await fut
           ^^^^^^^^^
   File "[/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/_kaleido_tab.py", line 223](http://localhost:8890/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/_kaleido_tab.py#line=222), in _write_fig
    img, profile = await self._calc_fig(
                   ^^^^^^^^^^^^^^^^^^^^^
    ...<5 lines>...
    )
    ^
   File "[/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/_kaleido_tab.py", line 323](http://localhost:8890/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/_kaleido_tab.py#line=322), in _calc_fig
    raise e
 kaleido._kaleido_tab.JavascriptError: {'result': {'type': 'object', 'subtype': 'error', 'className': 'ReferenceError', 'description': 'ReferenceError: kaleido_scopes is not defined\n    at <anonymous>:1:26', 'objectId': '-8540391823105239674.1.1'}, 'exceptionDetails': {'exceptionId': 1, 'text': 'Uncaught', 'lineNumber': 0, 'columnNumber': 25, 'scriptId': '11', 'stackTrace': {'callFrames': [{'functionName': '', 'scriptId': '11', 'url': '', 'lineNumber': 0, 'columnNumber': 25}]}, 'exception': {'type': 'object', 'subtype': 'error', 'className': 'ReferenceError', 'description': 'ReferenceError: kaleido_scopes is not defined\n    at <anonymous>:1:26', 'objectId': '-8540391823105239674.1.2'}}}

ERROR	Thread(Thread-5 (run)) Task(Task-5) kaleido.kaleido:kaleido.py:write_fig()- Cleaning tasks after error.
 Traceback (most recent call last):
   File "[/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/kaleido.py", line 424](http://localhost:8890/Users/liamconnors/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/kaleido.py#line=423), in write_fig
    await asyncio.gather(*tasks, return_exceptions=True)
 asyncio.exceptions.CancelledError

---------------------------------------------------------------------------
CancelledError                            Traceback (most recent call last)
Cell In[1], line 6
      3 import pathlib
      5 fig = go.Figure(data=[go.Scatter(y=[1, 3, 2])])
----> 6 kaleido.write_fig_sync(fig, path="f2igure.png", kopts=dict(page_generator=pathlib.Path("[/Users/liamconnors/Desktop/kaleido-tests/template.html](http://localhost:8890/template.html)")))

File [~/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/__init__.py:150](http://localhost:8890/~/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/__init__.py#line=149), in write_fig_sync(*args, **kwargs)
    148 def write_fig_sync(*args, **kwargs):
    149     """Call `write_fig` but blocking."""
--> 150     _async_thread_run(write_fig, args=args, kwargs=kwargs)

File [~/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/__init__.py:138](http://localhost:8890/~/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/__init__.py#line=137), in _async_thread_run(func, args, kwargs)
    136 res = q.get()
    137 if isinstance(res, BaseException):
--> 138     raise res
    139 else:
    140     return res

File [~/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/__init__.py:129](http://localhost:8890/~/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/__init__.py#line=128), in _async_thread_run.<locals>.run(*args, **kwargs)
    126 def run(*args, **kwargs):
    127     # func is a closure
    128     try:
--> 129         q.put(asyncio.run(func(*args, **kwargs)))
    130     except BaseException as e:  # noqa: BLE001
    131         q.put(e)

File [~/miniforge3/envs/kaleido-tests/lib/python3.13/asyncio/runners.py:195](http://localhost:8890/~/miniforge3/envs/kaleido-tests/lib/python3.13/asyncio/runners.py#line=194), in run(main, debug, loop_factory)
    191     raise RuntimeError(
    192         "asyncio.run() cannot be called from a running event loop")
    194 with Runner(debug=debug, loop_factory=loop_factory) as runner:
--> 195     return runner.run(main)

File [~/miniforge3/envs/kaleido-tests/lib/python3.13/asyncio/runners.py:118](http://localhost:8890/~/miniforge3/envs/kaleido-tests/lib/python3.13/asyncio/runners.py#line=117), in Runner.run(self, coro, context)
    116 self._interrupt_count = 0
    117 try:
--> 118     return self._loop.run_until_complete(task)
    119 except exceptions.CancelledError:
    120     if self._interrupt_count > 0:

File [~/miniforge3/envs/kaleido-tests/lib/python3.13/asyncio/base_events.py:725](http://localhost:8890/~/miniforge3/envs/kaleido-tests/lib/python3.13/asyncio/base_events.py#line=724), in BaseEventLoop.run_until_complete(self, future)
    722 if not future.done():
    723     raise RuntimeError('Event loop stopped before Future completed.')
--> 725 return future.result()

File [~/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/__init__.py:86](http://localhost:8890/~/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/__init__.py#line=85), in write_fig(fig, path, opts, topojson, error_log, profiler, kopts)
     73 """
     74 Write a plotly figure(s) to a file.
     75 
   (...)     83 
     84 """
     85 async with Kaleido(**(kopts or {})) as k:
---> 86     await k.write_fig(
     87         fig,
     88         path=path,
     89         opts=opts,
     90         topojson=topojson,
     91         error_log=error_log,
     92         profiler=profiler,
     93     )

File [~/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/kaleido.py:424](http://localhost:8890/~/miniforge3/envs/kaleido-tests/lib/python3.13/site-packages/kaleido/kaleido.py#line=423), in Kaleido.write_fig(self, fig, path, opts, topojson, error_log, profiler)
    422             await _loop(f)
    423     _logger.debug("awaiting tasks")
--> 424     await asyncio.gather(*tasks, return_exceptions=True)
    425 except:
    426     _logger.exception("Cleaning tasks after error.")

CancelledError:

Originally posted by @LiamConnors in https://github.com/plotly/Kaleido/issues/354#issuecomment-3084698533