What causes "The forum is currently in maintenance mode." in flarum/framework?

Log in with an administrator account (admins bypass the check).

flarum/framework · info · MaintenanceModeException

The forum is currently in maintenance mode.

Error message

The forum is currently in maintenance mode.

What it means

CheckForMaintenanceMode::process throws MaintenanceModeException('The forum is currently in maintenance mode.') when the forum is switched to maintenance and the requesting user is neither an admin nor hitting an exempt route. Flarum uses this to take the site offline for everyone except administrators.

Solutions

Log in with an administrator account (admins bypass the check).
Wait for the maintenance window to end, or ask the admin to disable maintenance mode in the admin dashboard.
If specific endpoints (e.g. webhooks or health checks) must stay reachable, add their route names to the middleware's exempt routes configuration.

Example fix

// before: hitting a protected route during maintenance
// GET /api/discussions -> 503 MaintenanceModeException

// after: register the route as exempt when enabling maintenance
new CheckForMaintenanceMode($maintenance, ['health', 'webhook']);

Defensive patterns

Strategy: try-catch

Validate before calling

// before scheduled jobs hitting public endpoints, check status
const res = await fetch('/api/forum-status');
const inMaintenance = res.status === 503;

Try / catch

try {
  return await apiFetch('/api/discussions');
} catch (e) {
  if (isMaintenanceMode(e)) { scheduleRetry(e.retryAfter); return; }
  throw e;
}

Prevention

Check the admin dashboard / status endpoint before running user-facing automation.
Schedule maintenance during low-traffic windows and notify clients.
Add health-check route names to the exempt-routes list for monitors.
Handle 503 responses with backoff and retry in API clients.

When it happens

Trigger: Any request while the 'maintenance_mode' / downtime setting is enabled, from a non-admin actor, whose routeName is not in the exempt-routes list configured for the middleware.

Common situations: Users browsing during a planned upgrade; monitoring tools hitting public endpoints during maintenance; API clients (mobile apps) failing during maintenance windows; admins wondering why a secondary account can't log in.

Related errors

AI-assisted analysis of flarum/framework@4b939f6853 (2026-09-15). Data as JSON: /api/errors/27d2544c2295ed86. Report an issue: GitHub.

Appendix: source

Thrown at framework/core/src/Http/Middleware/CheckForMaintenanceMode.php:34

use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;

readonly class CheckForMaintenanceMode implements MiddlewareInterface
{
    public function __construct(
        private MaintenanceMode $maintenance,
        private array $exemptRoutes,
    ) {
    }

    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        $actor = RequestUtil::getActor($request);
        $isRouteExcluded = in_array($request->getAttribute('routeName'), $this->exemptRoutes, true);

        if (! $isRouteExcluded && $this->maintenance->inMaintenanceMode() && ! $actor->isAdmin()) {
            throw new MaintenanceModeException('The forum is currently in maintenance mode.');
        }

        return $handler->handle($request);
    }
}

View on GitHub (pinned to 4b939f6853)