BookStackApp/BookStack · error · NotifyException

errors.page_custom_home_deletion

Error message

errors.page_custom_home_deletion

What it means

TrashCan::ensureDeletable blocks deleting a Page that is currently the instance's custom homepage while the 'app-homepage-type' setting is 'page'. Deleting the active homepage would leave the site without a landing page, so it throws NotifyException with 'errors.page_custom_home_deletion' and a link back to the entity. The check only fires when the custom homepage is active; if inactive, deletion proceeds and the homepage reference is cleaned up.

Source

Thrown at app/Entities/Tools/TrashCan.php:117

    }

    /**
     * Ensure the given entity is deletable.
     * Is not for permissions, but logical conditions within the application.
     * Will throw if not deletable.
     *
     * @throws NotifyException
     */
    protected function ensureDeletable(Entity $entity): void
    {
        $customHomeId = intval(explode(':', setting('app-homepage', '0:'))[0]);
        $customHomeActive = setting('app-homepage-type') === 'page';
        $removeCustomHome = false;

        // Check custom homepage usage for pages
        if ($entity instanceof Page && $entity->id === $customHomeId) {
            if ($customHomeActive) {
                throw new NotifyException(trans('errors.page_custom_home_deletion'), $entity->getUrl());
            }
            $removeCustomHome = true;
        }

        // Check custom homepage usage within chapters or books
        if ($entity instanceof Chapter || $entity instanceof Book) {
            if ($entity->pages()->where('id', '=', $customHomeId)->exists()) {
                if ($customHomeActive) {
                    throw new NotifyException(trans('errors.page_custom_home_deletion'), $entity->getUrl());
                }
                $removeCustomHome = true;
            }
        }

        if ($removeCustomHome) {
            setting()->remove('app-homepage');
        }
    }

View on GitHub (pinned to 18f8469a1c)

Solutions

1. Change the homepage type first (Settings > Homepage: set to default or another option), then delete the page.
2. Set APP_HOMEPAGE_TYPE env / 'app-homepage-type' setting to a non-page value and re-run the deletion.
3. Point the homepage at a different page ('app-homepage' setting) before deleting the old one.
4. Catch NotifyException in deletion flows to show the message and redirect to the entity URL as the exception provides.

Example fix

// before
$trashCan->softDestroyPage($homePage); // throws if active homepage
// after
setting('app-homepage-type', 'default'); // or change via Settings UI
$trashCan->softDestroyPage($homePage);

if ((int) setting('app-homepage') === $page->id
    && setting('app-homepage-type') === 'page') {
    // change homepage first
    setting('app-homepage-type', 'default');
}

try {
    $trashCan->softDestroyPage($page);
} catch (\BookStack\Exceptions\NotifyException $e) {
    return redirect($e->getMessageUrl ?? '/')->with('error', $e->getMessage());
}

When it happens

Trigger: softDestroyPage (directly or via chapter/book/shelf cascade through ensureDeletable) on the page whose ID matches the 'app-homepage' setting while APP_HOMEPAGE_TYPE=page (set via 'app-homepage-type' setting).

Common situations: Admins deleting a landing page created early in setup; bulk deletes inadvertently including the homepage page; environments where the homepage setting was left pointing at a page after redesigns; automated cleanup scripts not aware of the homepage config.

Related errors

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

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