passbolt/passbolt_api · warning · NotFoundException

Please use .json extension in URL or accept…

Error message

Please use .json extension in URL or accept application/json.

What it means

assertJson is a guard used by all standard CRUD endpoints (create, delete, index, share, update, view) to enforce that the request is recognized as JSON. If the request neither has a .json extension nor is accepted as JSON (Accept: application/json or Content-Type application/json), CakePHP's request->is('json') is false and a NotFoundException is raised directing the client to request JSON.

Solutions

1. Add .json to the endpoint URL (e.g. /users.json)
2. Send header Accept: application/json with the request
3. If using POST/PUT, also send Content-Type: application/json so CakePHP detects the JSON request

Example fix

// before
curl https://passbolt.example.org/resources/view/<id>
// after
curl -H 'Accept: application/json' https://passbolt.example.org/resources/view/<id>.json

// before calling any CRUD endpoint
if (!path.endsWith('.json')) path += '.json';
headers['Accept'] = 'application/json';

const assertsJson = (headers: Record<string,string>) => /application\/json/i.test(headers.Accept ?? '');

try { ... } catch (NotFoundException $e) { // 404 'Please use .json extension...'
    retry with Accept: application/json and .json URL
}

When it happens

Trigger: Calling any JSON API endpoint without a .json URL extension while the Accept header does not include application/json — e.g. curl without headers hitting /users/index, /shares/update, /resource/view, or a DELETE without .json.

Common situations: curl/Postman requests missing the Accept header; browser navigation to API routes; clients upgraded to endpoints that now assert JSON; proxies stripping Accept headers.

Related errors

• Ajax/Json request not supported.
• This is not a valid Ajax/Json request.
• This is not a valid Ajax/Json request.
• This is not a valid Ajax/Json request.
• Ajax/Json request not supported.

AI-assisted analysis of passbolt/passbolt_api@31c1bbc10f (2026-09-17). Data as JSON: /api/errors/45ae3cbed3b88915. Report an issue: GitHub.

Appendix: source

Thrown at src/Controller/AppController.php:205

            'plugin' => null,
            'controller' => 'AuthLogin',
            'action' => 'loginGet',
            '_method' => 'GET',
        ]);

        $this->loadComponent('Authentication.Authentication', [
            'logoutRedirect' => $loginUrl,
        ]);
    }

    /**
     * @throws \Cake\Http\Exception\NotFoundException if request is not JSON
     * @return void
     */
    protected function assertJson(): void
    {
        if (!$this->request->is('json')) {
            throw new NotFoundException(__('Please use .json extension in URL or accept application/json.'));
        }
    }

    /**
     * @throws \Cake\Http\Exception\BadRequestException if request data is not an array or is empty
     * @return void
     */
    protected function assertNotEmptyArrayData(): void
    {
        $data = $this->getRequest()->getData();
        if (!is_array($data) || !count($data)) {
            throw new BadRequestException(__('The request data can not be empty.'));
        }
    }

    /**
     * @inheritDoc
     */

View on GitHub (pinned to 31c1bbc10f)