Lesson 21 / 22 · Commentail 1.3.2
Start with the observed symptom instead of reinstalling everything. A missing widget, wrong Site and missing email need different checks.
Collect basic evidence
Use the environment actually running the site:
python --version
python -m pip show commentail Django wagtail
python manage.py check
python manage.py showmigrations commentail
Record versions and the exact error. For support, describe reproduction steps, expected action, actual result, database type and proxy topology. Remove user email, cookies, keys, complete messages and protected links. Use YOUR_API_KEY and variable names in examples.
Widgets and forms
| Symptom | First check |
|---|---|
| No Comments tab |
Actual Page template has the widget; dynamic include dependency is declared
|
| No public widget |
Live Page, correct Site/root, not Hidden, visitor has target access
|
| Unknown template tag |
load commentail_tags in this template and commentail in INSTALLED_APPS
|
| CSS/JS 404 |
collectstatic, STATIC_URL/STATIC_ROOT and server asset handling
|
| Submission 403 | CSRF token, cookies, origin/HTTPS/proxy and middleware; retain CSRF |
| Guest form unavailable | Mail backend/settings, Send emails and access policy |
| CAPTCHA missing | New guest versus remembered proof, JavaScript, key domains, CSP/blocker |
| Immediate throttling | Actual proxy peer, shared IP, form issuance quotas and repeat frequency |
| Editing unavailable | 15-minute deadline, accepted reply, pending revision or closed discussion |
| Status | Meaning | What to check |
|---|---|---|
| Queued | The job is waiting for processing | The real schedule, environment and database |
| Failed | Sending failed |
The error category, transport, templates, Site addressing and provider events
|
| Sent | The backend accepted the email | Delivery and inbox placement: the status alone does not confirm either |
Console output appears in the worker terminal, not necessarily the web server. Correct a wrong link domain in Site/HTTPS settings rather than manually rewriting email text.
Performance
Do not shared-cache private forms. Inspect host callbacks first: remote avatar requests or profile lookups per card can dominate rendering. Measure SQL, response time and backlog on a representative copy. A global recent list may inspect more candidates than limit when many targets are inaccessible. Synthetic benchmarks do not promise production capacity.
Verify as a reader
Repeat the failing step in another browser, then check a neighboring flow: replies after main-form changes, Russian email after an override, restricted content after adapter changes. Package tests do not validate your DNS, external account or host CSS.
Commentail has no separate REST API, uploads, likes, reports, rich text or live updates. Their absence is not an installation error. See troubleshooting and example testing for additional diagnostics.
Related lessons
- 2. Add Commentail to an existing Wagtail site
- 8. Schedule email processing and cleanup
- 22. Complete technical settings reference
Choose a sign-in method or comment as a guest below.