Errors and how to fix them

Consider this a field guide. Every error below was reproduced against the current release, and each entry tells you what the message means and what to change. The exception type is your first clue about where to look: ChameleonRobynException comes from this package and usually means a wiring problem, while ValueError, NameError and KeyError come from Chameleon and usually mean a template problem.

From chameleon-robyn

You must call global_init() before rendering templates.

A template was rendered before the engine was initialized. Call global_init() at startup, before the first request. In tests this usually means a fixture called clear() and nothing re-initialized afterwards; see Testing your handlers.

The specified template folder must be a folder, it's not: ...

The path passed to global_init() does not exist or is a file. Nine times out of ten it is a relative path that was correct from one working directory and wrong from another. Build it from __file__:

template_folder = (Path(__file__).resolve().parent / 'templates').as_posix()

Invalid return type <class '...'>, we expected a dict or Response as the return value.

A decorated handler returned something other than a dict or a Robyn Response. The most common culprit is <class 'NoneType'>: the handler fell off the end without a return, often after a not_found() call was commented out during debugging. Return the model dict.

__response_callback__ must be callable, got <class '...'>.

The reserved key holds a value that is not a function. Pass the function itself, not the result of calling it: '__response_callback__': set_cookie, not set_cookie().

'encoding' is reserved by Chameleon's render() and cannot be a template variable; rename the key.

Chameleon’s render() takes encoding as a named parameter, so the two would collide. Pick another name for that variable, such as charset or file_encoding.

ChameleonRobynNotFoundException escapes to Robyn

not_found() was called outside a @template-decorated handler, so nothing caught it. Either decorate the handler or return chameleon_robyn.response('errors/404.pt', status_code=404, message='...') instead.

From Chameleon

ValueError naming a template file

The template does not exist under the template folder. Check these in order:

  1. The path is relative to the folder you passed to global_init(), not to the current file.
  2. With auto-naming, the expected file is <module>/<function>.html or <module>/<function>.pt, where <module> is the last segment of the handler’s module name. For a script run directly it is the script’s file name, so index() in app.py expects app/index.pt (with __main__/index.pt as a fallback).
  3. A not_found() call expects errors/404.pt to exist unless you passed another template.

NameError: <name>

The template uses a variable the handler did not pass. Chameleon’s message is generous here: it reports the expression, the file and the line. Add the key to the returned dict, or guard the expression in the template with tal:condition.

KeyError: ':class', KeyError: '@click' or similar

An Alpine.js, htmx or Vue-style attribute was parsed under Chameleon’s restricted namespace, which mistakes it for an unknown XML prefix. Pass restricted_namespace=False to global_init() or to ChameleonTemplate. See Writing templates.

A parse error naming a file and line

Chameleon templates must be well-formed. Unclosed tags, a stray < in text, or an attribute without quotes stop the parser cold. Fix the markup at the reported line. Write &lt; for a literal less-than sign and &amp; for an ampersand in text.

Things that look like bugs but are not

Template edits do not show up

auto_reload is False, which is the default. Pass auto_reload=True in development. See Configuration.

A second global_init() call changed nothing

cache_init defaults to True, so a call made while the engine is initialized is ignored. Pass cache_init=False or call clear() first.

The 404 page came back as text/html from an XML handler

By design. not_found() always renders with status 404 and text/html, regardless of the handler’s content_type and status_code. To return a 404 in another format, build it with response(..., status_code=404, content_type='application/xml') and return it.

A $ shows up wrong in the page

${ starts an expression. Write $${price} to output a dollar sign followed by the value.