Troubleshooting

Symptom-driven reference for common issues. Sections are ordered from most frequent to most specialised. For background on permissions, connections, audit policy, and security settings, see the linked pages.

Console / app doesn't open (blank page or stuck loader)

You open Components → Next DB → Dashboard and the editor never appears.

1. Built files missing — A blank page usually means Next DB's built files aren't present, which only happens with custom or source builds. Reinstall the official package from nextsoftware.dev.
2. Browser console errors — Any JavaScript error during start-up will prevent the app from mounting. Check the browser console (F12) for errors from a template or plugin.
3. PHP version below 8.1 — Next DB requires PHP 8.1 or higher. On older PHP the backend throws a fatal error before the page renders. Check System → System Information → PHP Version. Upgrade PHP or choose a host that supports 8.1+.
4. Component not enabled — Confirm the component is published in System → Manage → Extensions and that the Components → Next DB menu item is enabled and accessible to the logged-in user group.

"Permission denied" on an operation

An operation that used to work (or that you expect to work) returns a permission error.

1. No profile assignment — Every non-Super User must be assigned to a profile. If the user is not covered by any profile they receive a blanket deny. Open Components → Next DB → Profiles and verify an assignment exists for the user or their group. See Profiles & ACL.
2. Profile assignment changed — Direct user assignment takes priority over group assignment. A recent direct assignment may have replaced a more permissive group profile. Check both the user-level and group-level assignments in the Profiles list.
3. Operation not granted in the profile — Each profile's permission set lists allowed operations per connection scope (Browse, Insert, Update, Delete, Truncate, Structure, Export, Import). If the operation was removed, Next DB blocks it before any SQL runs. Edit the profile and re-enable the operation.
4. Connection not included in profile — A profile may grant operations on the Joomla DB but not on attached connections. Verify that the connection is included in the profile, or covered by the default.
5. SQL console disabled — If the SQL console permission is off, every request to the SQL console is refused regardless of the statement. Turn on Allow SQL console in the profile editor. See SQL Console and Profiles & ACL.

"This table is protected and cannot be modified"

An insert, update, delete, truncate, or structure change is refused with a protection message, even when logged in as a Super User.

Core-table protection is enforced on the server — it applies to everyone including Super Users, because protecting the live Joomla install is the intent.

The two messages you may see are:

"This table is protected and cannot be modified. It is a Joomla core table or a database system object on a protected connection."

"This statement targets a protected Joomla core or system table and was refused. Disable core-table protection on this connection to allow it."

1. It is a Joomla core table on the Joomla DB — Joomla core tables such as users, user-groups, access and extensions are always write-protected on the Joomla database. This cannot be disabled for the Joomla DB. Read and browse operations still work; mutations are blocked to protect the live install.
2. It is a database system object — The database's internal system tables are blocked on every protection-enabled connection, regardless of engine.
3. You need to mutate such a table on an attached (external) connection — Core-table protection is opt-in per stored connection and can be turned off for non-Joomla databases. Open Components → Next DB → Connections, edit the relevant connection, and disable Protect core tables. This option does not exist for the Joomla DB entry. See Connections and Security.
4. The SQL console refused a statement — The SQL console performs a best-effort scan of raw statements. If a DROP, TRUNCATE, UPDATE, or DELETE targets a protected identifier, the console refuses it before execution. Either run the statement outside Next DB, or disable core-table protection on an external connection and re-run.

Connection test fails

Saving a new connection or clicking Test on an existing one fails.

1. Driver mismatch — Confirm the driver choice matches the actual database engine. For example, selecting MySQL for a MariaDB 10.6+ server with ed25519 authentication may fail; choose MariaDB where offered.
2. Host not reachable from the PHP process — The connection originates from PHP on the web server, not your browser. Some hosts block outbound database connections from the web stack. Test reachability with a small PHP CLI script on the server before blaming Next DB. Check firewall rules and that the target port (3306 / 5432 / etc.) is open.
3. PDO extension not installed — PHP needs the matching driver extension: pdo_mysql for MySQL/MariaDB, pdo_pgsql for PostgreSQL, pdo_sqlite for SQLite. Check System → System Information → PHP Information and search for the module. Install it via your hosting control panel or package manager, then restart PHP-FPM/Apache.
4. Encrypted password cannot be decrypted — Passwords are encrypted with a key derived from the Joomla site secret stored in configuration.php. If the site secret changed (e.g. after a site migration or reset), saved passwords can no longer be unlocked and the connection test will report a decrypt failure. Re-enter the password in the connection editor to re-encrypt it with the current secret.
5. Wrong port or socket — For MySQL/MariaDB socket connections, the host field must be left empty or set to localhost and the socket path provided. TCP connections require an explicit IP or hostname and port. Check the connection editor carefully. See Connections.

SQLite connection rejected or path error

Saving or testing a SQLite connection returns a path-validation or permission error.

1. No security base directory set — To prevent arbitrary file access, Next DB confines SQLite file paths to a configurable allow-list directory. If no base directory has been configured, SQLite connections cannot be created by non-Super Users, and the connection editor will warn you. Go to Components → Next DB → Settings → Security and set a SQLite base directory. See Security.
2. Path is outside the allowed base directory — The full resolved path of the .sqlite file must fall within the configured base directory. Paths that resolve outside it (even via symlinks) are rejected. Move the file into the allowed tree or update the base directory setting.
3. Path traversal detected — Sequences such as ../ in the path are refused outright, regardless of where they resolve. Use an absolute path without traversal sequences.
4. Non-Super Users cannot create SQLite connections — Until a Super User configures the SQLite base directory in Security settings, non-Super Users receive an error when attempting to create a SQLite connection. Ask a Super User to configure the base directory first.
5. File not readable by the PHP process — Even a valid, in-scope path will fail if the PHP process does not have read (and write, for mutations) permission on the file. Check filesystem ownership and permissions.

"Multi-statement" error in the SQL console

Pasting a script with multiple statements into the SQL console returns an error about multi-statement input.

The SQL console is designed for single-statement execution. It runs one statement per request to ensure accurate result display, error reporting, and audit recording. It does not accept semicolon-delimited scripts.

1. Run one statement at a time — Split your script and execute each statement individually in the console.
2. Use Import for scripts — The Import feature (available from the table toolbar and the connection/database level) accepts .sql script files with multiple statements. The statements are split at semicolons (respecting quoted text) before being sent one by one. See Export & Import and SQL Console.
3. Stored procedures / triggers — These contain semicolons inside the body. Create them with your database's own tools, then manage them in Next DB's structure view.

Audit log isn't recording entries

Mutations are succeeding but nothing appears on the Audit page, or only some operations are recorded.

1. Operation type not enabled in policy — The global audit policy (and any per-profile override) specifies which operation types are recorded (Browse, Insert, Update, Delete, Structure, Export, Import, and configuration changes). If the type is not enabled, no entry is written. Go to Components → Next DB → Settings → Audit and review the global policy. See Audit Policy.
2. Per-profile override is more restrictive — A profile with an Audit override may be recording fewer operations than the global policy. Open the profile in question and check the Audit section.
3. Failures not enabled — Failed operations are only recorded when Record failures is on. A DELETE that raised a constraint violation otherwise leaves no trace.
4. Audit table unreachable — Audit writes are best-effort: if the audit log table is missing or the Joomla DB connection drops at write time, the original operation still succeeds silently. Verify the table exists in the Joomla database; if it is missing, re-run the component's install SQL or reinstall the component.
5. Retention window pruned the entries — Each entry carries its own expiry, computed from the retention policy at the time of writing. If the retention window was set to a very short period, old entries are pruned on the next Audit page load or scheduled task run. Increase the retention window, then re-trigger the operations to generate new entries.
6. Scheduler task not running — The bundled pruning task handles background retention; it does not affect recording. If the Audit page is slow, confirm the task is enabled in Components → Scheduled Tasks. Recording itself does not depend on the scheduler.

Joomla update system not finding or downloading updates

The Update Manager shows no updates, shows an error, or the download fails.

1. Download key missing or expired — If the Next DB update server requires a download key, enter it in System → Update → Update Sites. Click the Next DB update site name and enter the key in the Download Key field. An expired or wrong key causes errors that the Update Manager reports as "no update available".
2. Update server unreachable — Confirm the web server can make outbound HTTPS connections to the update server hostname. Some hosting providers block outbound HTTP. Check error logs or test with a CLI HTTP request from the server.
3. Manifest version mismatch — The update server compares your installed version against the available manifest. If you installed from a custom build with an unofficial version string, the comparison may never match. Reinstall from an official package to restore a clean version baseline.
4. Joomla cache stale — Joomla caches update manifests. Go to System → Clear Cache and clear all caches, then try System → Update → Joomla Extensions again.

Component conflicts with other extensions

Next DB triggers a PHP error or JavaScript crash that appears to come from another extension, or another extension breaks after Next DB is installed.

1. Conflict with another extension's bundled library — A rare conflict can occur if another extension bundles an incompatible copy of the same database engine library. Resolution: update both extensions, contact the other extension's author, or disable the conflicting extension.
2. JavaScript error from another extension — Open the browser developer tools (F12 → Console). A script error in a third-party template plugin or system plugin can prevent the application from mounting even though Next DB itself is fine. Disable plugins one by one (or switch to a stock Joomla template) to isolate the source.
3. Template CSS clashes — Next DB ships a conflict-patch stylesheet that fixes common template CSS conflicts. Very aggressive template resets (e.g. blanket * { box-sizing: content-box } rules) may still bleed into the editor. Add targeted overrides in your template's user.css or custom.css file. Do not edit Next DB's file — it will be overwritten on the next update.
4. Other PHP errors — Check the Joomla error log (administrator/logs/) for class or autoloader errors and report them with your support request.