BookStackApp/BookStack · error · PermissionsException

User does not have permission to create a chapter within the

Error message

User does not have permission to create a chapter within the chosen book

What it means

ChapterRepo::move, after locating a valid parent Book, checks userCan(Permission::ChapterCreate, $parent). If the current user lacks chapter-create permission on the target book, it throws PermissionsException('User does not have permission to create a chapter within the chosen book'). Moves require create rights in the destination, not just view rights.

Source

Thrown at app/Entities/Repos/ChapterRepo.php:98

    }

    /**
     * Move the given chapter into a new parent book.
     * The $parentIdentifier must be a string of the following format:
     * 'book:<id>' (book:5).
     *
     * @throws MoveOperationException
     * @throws PermissionsException
     */
    public function move(Chapter $chapter, string $parentIdentifier): Book
    {
        $parent = $this->entityQueries->findVisibleByStringIdentifier($parentIdentifier);
        if (!$parent instanceof Book) {
            throw new MoveOperationException('Book to move chapter into not found');
        }

        if (!userCan(Permission::ChapterCreate, $parent)) {
            throw new PermissionsException('User does not have permission to create a chapter within the chosen book');
        }

        return (new DatabaseTransaction(function () use ($chapter, $parent) {
            $this->parentChanger->changeBook($chapter, $parent->id);
            $chapter->rebuildPermissions();
            Activity::add(ActivityType::CHAPTER_MOVE, $chapter);

            $this->baseRepo->sortParent($chapter);

            return $parent;
        }))->run();
    }
}

View on GitHub (pinned to 18f8469a1c)

Solutions

1. Grant the user's role 'Create chapter' permission, or add a book-level restriction allowing create for them.
2. Perform the move as a user/token with sufficient privileges.
3. Pre-check userCan(Permission::ChapterCreate, $book) before calling move and show a permission error in the UI.
4. Catch PermissionsException around move() to render a friendly message.

Example fix

// before
$chapterRepo->move($chapter, $bookId);
// after
$parent = $entityQueries->findVisibleByStringIdentifier($bookId);
if (!userCan(\BookStack\Permissions\Permission::ChapterCreate, $parent)) {
    abort(403, 'No permission to create chapters in the target book');
}
$chapterRepo->move($chapter, $bookId);

$parent = $entityQueries->findVisibleByStringIdentifier($identifier);
if ($parent instanceof \BookStack\Entities\Book
    && !userCan(\BookStack\Permissions\Permission::ChapterCreate, $parent)) {
    abort(403, 'Missing chapter-create permission on target book');
}

try {
    $chapterRepo->move($chapter, $identifier);
} catch (\BookStack\Exceptions\PermissionsException $e) {
    return response()->json(['error' => $e->getMessage()], 403);
}

When it happens

Trigger: move($chapter, $bookIdentifier) invoked by a user whose role lacks 'chapter-create' (via role permission or entity-level restrictions) on the destination book.

Common situations: Admin scripts/API integrations running as a low-privilege API token; role permission changes removing chapter-create; per-book restrictions granting view but not create; moving chapters into restricted books the user can see but not edit.

Understand the failure class

Background: "You do not have permission" / 403 Forbidden errors: authenticated but not allowed — causes and fixes across open-source libraries — this error's family across 31 libraries.

Related errors

• User does not have permission to create a page within the ne
• errors.chapter_not_found
• errors.page_not_found
• errors.api_user_no_api_permission
• Book to move chapter into not found

AI-assisted analysis of BookStackApp/BookStack@18f8469a1c (2026-09-02). Data as JSON: /api/errors/5b53242f2920b7dd. Report an issue: GitHub.