Permission Errors

This document covers access and capability errors that can prevent administrators or other users from accessing the ADP Car Market Hub plugin features, importing vehicles, or managing listings.

When to use this document

Read this document when:

• A user receives a "Permission denied" or "You do not have permission to perform this action" message when using the plugin admin.
• A user cannot see the plugin admin menu or specific admin tabs.
• A user cannot edit, publish or delete vehicle (as24ci_car) posts.
• Capability-related errors appear in the plugin log after an update or role change.

Overview

The plugin uses two distinct access layers:

1. Plugin management capability (manage_as24_imports) — controls access to the plugin admin interface (Settings, Importer, Tools, Logs, Market Hub, PDF Manager, etc.) and all administrative AJAX actions. This capability is granted exclusively to the built-in administrator role.

2. Custom Post Type (CPT) capabilities — a set of WordPress post capabilities for the as24ci_car post type that control who can read, create, edit, publish and delete vehicle posts. These capabilities are granted to both the administrator role and the custom AS24 Editor role created by the plugin.

Editors, Authors and Subscribers have no access to either layer by default. The WordPress built-in editor role also does not receive these capabilities.

Roles and capabilities reference

Plugin management capability

Every admin AJAX handler and admin POST handler in the plugin checks current_user_can('manage_as24_imports') before executing. Any user without this capability receives a 403 Permission denied response.

CPT capabilities

The following capabilities are assigned to both the administrator and as24ci_editor roles:

Custom role: AS24 Editor (as24ci_editor)

The plugin creates a custom WordPress role named AS24 Editor (slug: as24ci_editor) during activation. This role grants all CPT capabilities listed above but does not grant manage_as24_imports. AS24 Editors can manage vehicle posts from the standard post list table but cannot access the plugin admin pages, import, or change settings.

Diagnostic steps

Step 1: Confirm that capabilities have been assigned

Capabilities are assigned during plugin activation and updated via an internal migration system. If a user cannot access the plugin admin, verify:

1. Log in as a WordPress Administrator.
2. Go to the plugin admin and open the System & Help tab.
3. Check the system status output for any capability-related warnings.

If the capabilities were not assigned (for example, on a multisite install where the plugin was activated network-wide but never run in admin context), proceed to Step 2.

Step 2: Re-trigger the capability migration

The capability assignment runs automatically on each admin page load via plugins_loaded, but only once per capability version and only for users who have manage_options. To force it to re-run:

1. Log in as a WordPress Administrator.
2. Deactivate the plugin from Plugins.
3. Reactivate the plugin. The activation hook calls ensure_roles_and_caps() directly.
4. Test whether the affected user now has the correct access.

Step 3: Check the user's role

1. Go to Users in the WordPress admin.
2. Open the affected user's profile.
3. Confirm the user's role is set to Administrator (for full plugin management access) or AS24 Editor (for CPT management only).
4. If the user has a custom role from a third-party plugin, that role may not include the required capabilities. In that case, a developer must add the capabilities manually or use a capability management plugin.

Step 4: Check for a conflicting capability plugin

If a capability management plugin (such as Members, User Role Editor, or PublishPress Capabilities) is active:

1. Open the capability plugin's interface.
2. Verify that the manage_as24_imports capability is assigned to the administrator role.
3. Verify that the CPT capabilities listed above are assigned to both administrator and as24ci_editor.
4. Save any changes and retest.

Step 5: Multisite considerations

On a WordPress multisite installation:

• Plugin capabilities are stored in the wp_user_roles option of each sub-site's database table.
• If the plugin is network-activated, the capability migration runs in the context of the current site only when an administrator visits the admin.
• A super admin has implicit access to all sites, but regular administrators on individual sites must have the manage_as24_imports capability on their specific site.

Verify this behavior in the current plugin version before publishing for multisite deployments.

Operational notes

• Capability assignments are stored in the WordPress roles option (wp_user_roles). Resetting or replacing this option (for example via a site migration or a security plugin that regenerates roles) will remove the plugin's custom capabilities. Reactivating the plugin will restore them.
• The as24ci_editor role is created once on activation. If it is deleted (for example via a role management plugin or a database reset), reactivating the plugin will recreate it.
• All plugin admin AJAX endpoints require both the correct capability and a valid WordPress nonce. A "Permission denied" response to an AJAX request can indicate either a missing capability or an expired nonce (for example, after a long session or a page cached without nonce regeneration).
• The maybe_upgrade_caps() function runs on the plugins_loaded hook in admin context. It checks a stored version number and only runs when a capability migration has not yet been applied. After it runs, it updates the stored version so it does not run again until the next migration version is released.

Troubleshooting

Related documents

• Troubleshooting Overview
• Import Errors
• Cron Errors