Bitrix24 On-Premise Updates & Maintenance: Versions, Patches and Best Practices

How the SiteUpdate System Works

Bitrix24 (Alaio)'s built-in SiteUpdate technology downloads compressed update packages directly from the vendor's servers through the admin panel, applies them without touching the public-facing part of the portal, and verifies each file before installation - so a failed patch does not silently corrupt a live environment.

SiteUpdate is the update engine embedded in every on-premise edition. When you open Marketplace → Platform Update in the admin panel, the system authenticates using your license key, retrieves a manifest of available updates and new modules, compresses the payload for faster transfer, and applies patches server-side. The public portion of the portal remains live throughout; end users are unaffected during a normal update.

Key facts about SiteUpdate (as of 2026):

• Updates are delivered over HTTPS from Bitrix vendor infrastructure.
• The license key is validated on every update request - an expired or inactive license blocks downloads.
• SiteUpdate itself can become outdated; if the Install Updates button is greyed out, update SiteUpdate first via Marketplace → Platform Update → Update SiteUpdate System.
• Two update channels exist: Stable (default, fully tested) and Beta (early access, may contain bugs). Switch channels under Marketplace → Platform Update → Advanced → Beta Version Toggle.
• Updates received while your license was lapsed become available again the moment you renew - you will not lose access to historical releases.

For teams running Bitrix24 in a restricted network (air-gapped or private cloud), update packages must be mirrored to a local repository in advance. See the discussion of deployment environments in our guide to deploying self-hosted Bitrix24 on AWS, Azure, or a private cloud.

Prerequisites Before Every Update

Before triggering any update, confirm that PHP meets the minimum version requirement, that your license is active, and that a verified full backup exists - all three are hard blockers: without them, either the update system refuses to run or a rollback becomes impossible.

PHP version requirements (as of 2026)

The admin panel shows the active PHP version under Settings → Performance → PHP. If the version is below the minimum, the update system will display a warning and refuse to proceed.

Required PHP extensions

The following extensions must be present and correctly configured:

• mbstring - must be installed; mbstring.func_overload must equal 0; mbstring.internal_encoding in php.ini must be empty (use default_charset instead)
• XML - used by the update system itself
• GD + FreeType - required for charts, CAPTCHA, and statistics modules
• Zlib - used for update package compression
• OPcache - strongly recommended for performance
• memory_limit set to at least 256M

Missing or misconfigured extensions will cause the update system to block installation with explicit warnings.

License and subscription

An active updates-and-support subscription is required to receive updates. Check license status in the admin panel; plan renewals before expiry to avoid a gap. If the license lapses, the portal continues to function at a degraded level but no new updates or security patches can be applied.

Safe Update Procedure: Step-by-Step Checklist

The non-negotiable sequence is: verify PHP → backup everything → update on staging → review the changelog → apply to production during a low-traffic window → run smoke tests → keep the backup available for at least 48 hours.

Use this checklist for every production update:

• Verify PHP version - confirm the server runs PHP 8.2 or higher (8.3+ recommended as of 2026)
• Check mbstring.func_overload - value must be 0 in php.ini
• Confirm active license - license key accepted by update server
• Create a full backup - files + database, stored outside the application server (see our backup and disaster recovery strategy)
• Update on a staging copy first - clone the production portal, run the update, test all critical workflows
• Read the release notes - identify any breaking changes, deprecated APIs, or new PHP requirements
• Update SiteUpdate itself if prompted before proceeding to platform updates
• Update all Marketplace modules (platform modules, then third-party solutions) under Marketplace → Update Solutions
• Schedule a low-traffic maintenance window - communicate downtime to users if needed
• Apply update to production via Marketplace → Platform Update → Install Recommended Updates
• Run smoke tests - CRM, tasks, email, telephony integrations, custom modules
• Monitor logs and error rates for 24-48 hours post-update
• Keep the pre-update backup accessible for at least 48 hours

A staging-first update flow connects the key systems involved.

The following diagram shows the recommended two-stage update flow: a staging environment receives and validates the update first; only after successful smoke testing does the same update package get applied to production, with a rollback path always available via the pre-update backup.

flowchart LR
    VENDOR[Bitrix Vendor\nUpdate Server] -->|SiteUpdate / license key| STAGING[Staging Portal]
    STAGING -->|Smoke tests pass| PROD[Production Portal]
    STAGING -->|Tests fail| ROLLBACK[Rollback from Backup]
    BACKUP[Full Backup\nfiles + DB] --> ROLLBACK
    PROD --> MONITOR[Post-update\nLog Monitoring]
    MONITOR -->|Issues detected| ROLLBACK

Common Update Failures and How to Fix Them

The four most frequent on-premise update failures are PSR/Composer library conflicts from third-party modules, core files overwritten by direct edits, a PHP version below the minimum, and corrupted database tables - each has a specific, reproducible fix.

PSR/Composer conflict: detailed fix

This is the most technically involved failure. Third-party modules sometimes bundle their own vendor/ directories containing older versions of PSR interface packages. When Bitrix24 updates its own PSR dependencies, a version mismatch triggers a PHP fatal error that prevents the portal from loading.

Resolution steps:

1. Identify the conflicting module from the stack trace.
2. Add version constraints for psr/log, psr/container, and psr/http-message in /local/composer.json matching the versions required by the updated Bitrix24 core.
3. Run composer update (or composer install) from the /local/ directory.
4. If the third-party module's own vendor/ still overrides the pinned versions, contact its developer - or temporarily disable the module until a compatible release is available.

Upgrading PHP on a Self-Hosted Portal

Upgrading PHP on a live Bitrix24 server is a multi-step sequence: backup first, then update all platform modules and Marketplace solutions to their latest versions on the old PHP, then upgrade PHP, then verify again - reversing those steps is the most common cause of post-upgrade failures.

The correct sequence (per Bitrix official guidance, translated):

1. Create a full backup of the installation - files and database. For VMBitrix virtual machine deployments, a full VM snapshot is acceptable.
2. Update the platform core and all modules to the latest available versions: Settings → Marketplace → Platform Update.
3. Update all third-party Marketplace solutions: Marketplace → Update Solutions.
4. Upgrade PHP on the server to 8.3 (recommended as of 2026). - On VMBitrix: use the VM management menu → 1. Manage servers in the pool → 8. Update PHP and MySQL, select the target host or all, and confirm. An Ansible role runs automatically; logs are written to /opt/webdir/temp/bx_php_upgrade_*. - On a custom Linux stack: update via your package manager, migrate configuration from the old php.ini / extension configs, and restart Apache (systemctl restart httpd) or Nginx.
5. Run platform and solutions updates again - some updates are gated on the new PHP version and only become available after the PHP upgrade.
6. Check mbstring.func_overload is 0 in the active php.ini; check default_charset is set to UTF-8.

If errors appear in standard Bitrix modules after the PHP upgrade, contact Bitrix support. For errors in third-party modules (those containing a dot in their name, e.g., vendor.module), contact the module developer directly via the Marketplace support tab.

If the upgrade breaks something and you cannot immediately fix it, roll back to the previous PHP version, verify everything works, fix the incompatible modules, and then attempt the PHP upgrade again.

Ongoing Maintenance Regimen

A healthy on-premise Bitrix24 portal requires more than periodic version updates - it needs a structured weekly/monthly regimen covering backups, OS and PHP patching, log rotation, disk and RAID health checks, cron/agent health, slow-query analysis, and broken-table detection.

Recommended maintenance schedule

Key areas to monitor

Backups: Automated backups must be verified, not just scheduled. Store archives outside the application server - on a separate volume, NAS, or object storage. Test restore procedures periodically. A backup that has never been tested is not a backup.

OS and PHP patches: Operating system security updates should be applied monthly at minimum. PHP minor version updates (e.g., 8.3.x patch releases) close security vulnerabilities; treat them as routine maintenance, not exceptional events.

Log rotation: Bitrix24 on a busy portal generates significant log volume. Without rotation, logs fill the disk and crash the web server. Configure logrotate or equivalent for web server, PHP, and MySQL error logs.

Disk and RAID health: Monitor disk usage with alerting thresholds (warn at 80%, critical at 90%). On bare-metal deployments, check RAID array health weekly - a degraded RAID that goes unnoticed until a second drive fails means data loss.

Cron agents: Bitrix24 relies on cron-based agents for email delivery, event processing, and automation. A misconfigured or stuck agent queue silently degrades functionality. Check agent health under Settings → Tools → Agents.

Database table integrity: Run CHECK TABLE on the main Bitrix24 tables quarterly and after any abnormal server shutdown. Address innodb_log_file_size and buffer settings if MySQL performance degrades - a value of 64 MB is typically too small for a portal with active CRM usage.

Security scanner: Run the built-in Bitrix24 security scanner periodically (Settings → Security → Security Scanner). Outdated modules, enabled error display to end users, missing HSTS headers, and disabled two-factor authentication are all findings that frequently appear on portals that have drifted from maintenance schedules.

For a full security hardening approach, see our 25-point security hardening checklist.

The Golden Rule: Never Edit the Bitrix24 Kernel

Every file inside /bitrix/modules/ and /bitrix/ core directories is owned by the update system - any direct edit will be silently overwritten on the next update, and if those edits contained business-critical logic, it disappears without warning.

This is one of the most common sources of post-update breakage on self-hosted portals. A security audit of a real production portal found 23 modified files across 6 modules out of 109,188 checked - a low overall modification rate of 0.02%, but enough to cause problems when updates arrived for those specific modules.

The correct architecture for customizations:

• All custom code lives in /local/ - this directory is never touched by SiteUpdate.
• Business logic extensions use Bitrix24 event handlers registered from custom modules.
• UI customizations use component template overrides placed in /local/templates/ or /local/components/.
• Custom modules are developed as independent modules installed alongside the platform, not patches to core files.
• Integration logic (ERP sync, telephony, third-party APIs) is built as proper REST/webhook applications or local modules - never as edits to existing module files.

If your implementation partner or a previous developer did make direct kernel edits, the recommended remediation is to document what was changed, rebuild the logic correctly in /local/, revert the core files to their original state, and then update. Our experience across 1,300+ projects confirms that properly architected customizations survive every routine update without intervention.

For teams considering a move to self-hosted specifically to gain deeper customization control, see what becomes possible with self-hosted Bitrix24.

Working with a partner on self-hosting. Want the control of self-hosted Bitrix24 without running the server yourself? ACP Group can deploy and operate it for you - see managed self-hosted Bitrix24, support & maintenance plans, or request a turnkey deployment quote.