Troubleshooting

Common issues and how to resolve them. Sections are ordered from most frequent to most specialised.

Before working through any of them, one general tip: Next Exams logs operational failures — a webhook that would not send, a certificate that would not render — to the com_nextexams log category. Nothing is written until you enable it, because registering an always-on log file would write to disk on every install for a failure most sites never hit. Turn it on in System → Global Configuration → Logging by adding com_nextexams to Log Almost Everything / the logged categories list, reproduce the problem, then read administrator/logs/.

An exam page shows "not authorised" or nothing at all on the site

A visitor opens the menu item you created and does not get the exam.

1. The exam is not published — an unpublished exam is invisible to everyone but an author. Check the Published column in Authoring → Exams.
2. The menu item points at the wrong type — NextExams - Single Exam requires an exam to be selected in its own options; if none is chosen the page has nothing to render. NextExams - Exams lists published exams and needs no selection.
3. The Joomla access level excludes them — this is Joomla's own view level on the menu item, applied before Next Exams sees the request. A menu item set to Registered is invisible to guests regardless of the exam's own access rule.
4. The exam's own access gate is refusing them — that is a different check with its own message. See the next section.
5. The app is switched off — with the relevant app disabled in the App Manager, site views return 404 rather than rendering. Check Configuration → App Manager.

An examinee cannot start an exam

They reach the exam page but the Start button is refused, or they see a gate message.

Work through the gate in order — the first failing condition is the one reported.

1. Outside the opening window — Open from and Open until are absolute times. An exam whose window has not opened, or has closed, refuses the start.
2. Attempt cap reached — the exam's maximum attempts has been used up. Practice-mode attempts are excluded from the cap by design, so check whether you are looking at a practice attempt.
3. Cooldown still running — a cooldown period between attempts is enforced next to the cap. The remaining time is reported in the refusal.
4. Wrong or missing access code — for a code-gated exam the code is compared server-side. Codes are exact; leading and trailing spaces are stripped but case matters.
5. Not on the allow-list — for a restricted exam, the person must match a cohort, group, user or view level rule. A user who was added to a Joomla group after the cohort was mirrored will not appear until the cohort is refreshed.
6. Guest without the required details — an exam gated to identified guests will not start until the name and email fields are completed.

Answers are not saving, or the autosave indicator shows an error

The examinee is working but the save indicator reports a failure.

1. The Joomla session expired — the most common cause on long exams. The bundled session plugin re-authenticates in the background so this normally recovers by itself; if the plugin has been disabled, it will not. Check System → Manage → Plugins for System - NextExams Session.
2. The attempt is no longer in progress — a save against an attempt that has been submitted, force-submitted by an invigilator, or auto-submitted at the time limit is rejected. The runner cannot resurrect a finished attempt.
3. The attempt is paused — a paused attempt does not accept answer writes until it is resumed.
4. A server error on one save — this is recoverable and usually invisible. The runner tracks which answers the server has acknowledged and re-sends anything unconfirmed on the next save, so a single failed request does not lose work. Persistent failures need the server log.
5. A proxy or firewall stripping the CSRF token — every save carries a token in both the request header and the body. An aggressive intermediary that strips custom headers will still work; one that rewrites the body will not.

Results never appear — the examinee sees a pending notice

The attempt is submitted, but no score is shown.

1. The exam contains an essay — essays are graded by a person. Until every essay in the attempt is marked, the attempt is not fully graded and the review stays locked deliberately, so nobody sees a half-marked paper. Mark them in Results → Attempts.
2. Result release is not set to immediate — check the exam's Access & Release tab. The release policy can be immediate, after the exam closes, at a scheduled time, or manual. Under manual, results appear only when you release them.
3. The release time has not been reached — a scheduled release is an absolute time. Confirm it is in the past.
4. Answers are released separately — showing the correct answers is a distinct switch from showing the score. An examinee can legitimately see their score with the paper still hidden.

No certificate was issued

Someone passed but got no certificate.

1. The exam has no certificate template assigned — certificates are issued per exam, and the template selector defaults to none. Set it on the exam.
2. They did not pass — issue happens on a pass against the exam's pass mark, not on completion.
3. The attempt is not fully graded — an attempt still awaiting essay marking has no final result to issue against yet. It will issue once marking completes.
4. The Certificates app is switched off — with it disabled, nothing is issued. Existing certificates remain and stay downloadable once it is re-enabled.
5. The certificates plugin is disabled — issue-on-pass is driven by System - NextExams Certificates. If it has been disabled, passes are recorded but nothing is awarded.

Certificate PDFs fail to render or download

The record exists but the PDF errors, downloads empty, or shows mangled text.

1. A missing PHP extension — the bundled renderer needs mbstring, dom and iconv. This is the usual cause of an outright failure on a minimal host. Confirm them in System → System Information → PHP Information.
2. Mangled or missing characters — almost always an encoding problem in the font path rather than the template. The package ships DejaVu faces precisely so non-ASCII text renders; a template pointed at a font that lacks the glyphs will drop them.
3. QR code missing from the PDF — without the gd extension the QR falls back to SVG, which some viewers render poorly. Enabling gd switches it to a small PNG.
4. An old certificate looks wrong after a template edit — this is correct behaviour, not a fault. Each certificate is rendered from a snapshot frozen when it was issued, so editing a template never rewrites certificates already awarded.
5. PHP memory or execution limits — a heavy background image can push a render past a low memory_limit. Reduce the image or raise the limit.

Emails are not being sent

Submission confirmations, grading notices or reminders never arrive.

1. Joomla's own mail is not configured — test it first in System → Global Configuration → Mail with Send Test Mail. Next Exams sends through Joomla's mailer, so if that fails nothing else matters.
2. Notifications are switched off — check the master switch in Configuration → Settings → Notifications, and that the Notifications app is enabled in the App Manager.
3. The notifications plugin is disabled — immediate sending is driven by System - NextExams Notifications.
4. No template exists for that event — mail is template-driven. An event with no template row sends nothing. Check Configuration → Email templates.
5. The admin recipient is empty — admin-facing notices need an address in the notification settings; they are not sent to the site's own email by default.
6. A failed send is never retried — the immediate send is best-effort. Retries require the notification flush task, which you must create yourself. See Scheduled tasks.

Webhook deliveries stay pending or keep failing

Your endpoint never receives anything, or the delivery log fills with failures.

1. The URL resolves to a private address — this is the single most common cause during testing. Next Exams refuses to send to loopback, private, reserved or link-local addresses, checked at send time as well as save time, to prevent the site being used to reach internal services. A local receiver on 127.0.0.1 or 192.168.x.x will be blocked. For a genuine on-premises endpoint, enable the private-address opt-in in the webhook settings.
2. A redirect to somewhere else — redirect following is disabled deliberately, so an endpoint that answers 3xx never completes. Point the webhook at the final URL.
3. The endpoint is unpublished or subscribed to no events — both are silent no-ops. Check the endpoint's event checkboxes.
4. Signature verification failing on your side — the signature is an HMAC-SHA256 of the raw request body using that endpoint's secret. Recomputing it over a re-serialised copy of the JSON will not match, because key order and whitespace change.
5. Failures are never retried — as with email, retry needs the webhook flush task. Without it, a delivery that fails its immediate attempt sits pending. Deliveries give up and are marked failed after five attempts.

The live monitor board is empty, stale, or will not load

You open the board during an exam and see nothing, or nothing changes.

1. Nobody is actually in progress — the board shows in-progress attempts. A room where everyone has submitted is legitimately empty.
2. Monitoring is switched off — check the App Manager and the monitoring settings section.
3. The board looks frozen but is not — a quiet room deliberately costs almost nothing: when nothing has changed, the poll returns a tiny unchanged response instead of rebuilding the board. That is the intended behaviour, not a stall. Activity will appear at the next poll.
4. The poll interval is longer than you expect — the interval, the stale threshold and the examinee ping interval are all configurable, with non-zero floors so the board cannot be turned into a self-inflicted denial of service.
5. An invited invigilator gets nothing — grants are always scoped to a single exam. A link issued for one exam shows only that exam, by design. Check the grant has not expired and has not been revoked.
6. A PIN is being rejected after several tries — PIN entry is rate-limited per IP address, five attempts, precisely because six digits is guessable. Wait out the lockout.

An LTI launch fails

The LMS reports an error, or the launch lands on a Joomla error page.

1. openssl is unavailable — the tool generates its own RSA key pair on first use and signs tokens with it. Without the extension nothing works. Some hosts have PHP OpenSSL with no default configuration path; the component ships a minimal configuration file to cover that case.
2. The platform registration does not match — the issuer, client ID and deployment ID must match what the LMS sends exactly. A mismatched deployment ID is the most common single cause.
3. The JWKS URL is unreachable — the launch token is verified against the platform's public keys, fetched over HTTP. A server that cannot make outbound connections cannot complete a launch.
4. Clock skew — token timestamps are accepted within sixty seconds. A server clock that has drifted further will reject every launch. Check NTP.
5. A replayed launch — nonces are single-use. Reloading a launch URL will fail; the launch must be started again from the LMS.
6. Cookies blocked in the LMS iframe — a launch rendered inside a third-party iframe can have its cookies dropped by the browser. Launching in a new window is the reliable route.

An admin page is missing, or an endpoint returns 403

A nav item you expect is not there, or an action refuses with a permission error.

1. The app is switched off — a disabled app removes its nav item, its route and its dashboard widget, and its endpoints refuse with an APP_DISABLED code. Check Configuration → App Manager first; this is much more often the cause than a permission problem.
2. The role lacks the action — Next Exams uses its own roles, not Joomla's ACL, for fine-grained rights. A user needs a role granting that action on that feature. Joomla Super Users bypass this entirely.
3. No role is assigned at all — a user with Joomla admin rights but no Next Exams role sees a "no permission" screen rather than the application. Assign a role in the role editor.
4. Demo mode is on — while the demo dataset is installed, every mutating request from a non-Super-User is refused by design, so the site cannot be altered by visitors. Remove the demo data to restore normal writes.
5. Front-end access needs both — reaching the management application on the site requires Joomla's core.manage permission and a Next Exams role. Either one alone is not enough.

Joomla update system not finding or downloading updates

Updates are not offered, or the download fails.

1. Download key missing — Next Exams is served from our own update server and requires your key. Go to System → Update → Update Sites, click Next Exams Updates and enter it in the Download Key field. Without it the check may succeed while the download fails with "Failed to download package".
2. Update cache — Joomla caches update information. Use Check for Updates on System → Update → Extensions to force a refresh.
3. Server unreachable — the site must be able to make outbound HTTPS requests to nextsoftware.dev. Some hosts block outbound connections by default.

Conflicts with other extensions

Something breaks only when another extension is enabled.

1. A JavaScript error from another extension — open the browser console with F12. An uncaught error thrown by another extension's script can stop the runner's enhancements from initialising. The exam still submits in that state, because the runner is a real form, but the timer and autosave will not run.
2. A template overriding component output — a site template shipping its own com_nextexams overrides can lag behind an update. Move the override aside and retest before reporting a bug.
3. A caching plugin serving stale pages — page caching in front of an exam page can serve one examinee's rendered gate state to another. Exclude the exam and runner pages from full-page caching.
4. Another extension claiming the same events — the certificate, notification and webhook plugins all listen to attempt events. A third-party plugin that halts event propagation will silently suppress them.