Short answer: When a da build run fails, read the last screen of compiler output first (run builds through tee so you keep it), then /usr/local/directadmin/custombuild/custombuild.log for what CustomBuild called and installed. Check that no other build is still running before you touch .custombuild.lock, fix the cause (memory, disk, a missing -devel package or a stale custom/ file), and re-run only the failed component. To roll back, pin the previous version in custom_versions.txt and rebuild that component.
Applies to DirectAdmin 1.712 on AlmaLinux 9.8
We ran the read-only commands on our lab server (AlmaLinux 9.8, DirectAdmin 1.712) on 6 October 2026: da build, da build versions, da build used_configs, da build opt_help and the log and lock checks. We did not force a build failure on the lab; the fix steps are checked against the official DirectAdmin documentation.
Table of Contents
Where CustomBuild keeps its files and logs
Since DirectAdmin moved CustomBuild into the main binary, you run it as da build .... The working folder is still /usr/local/directadmin/custombuild/. On our 1.712 lab it contains:
| Path | What it is |
|---|---|
custombuild.log | High-level log: which command was called and what was installed |
options.conf | Your build choices (web server, PHP versions, MariaDB, mail) |
versions.txt | Versions CustomBuild will install, one name:version: line each |
custom_versions.txt | Your overrides of versions.txt (absent until you create it) |
configure/ | Stock configure flags per component (php, ap2, exim, …) |
custom/ | Your overrides of configure/ (absent until you create it) |
cache/ | Downloaded source tarballs |
mysql_backups/ | Database dumps taken before a MariaDB/MySQL update |
.custombuild.lock | Lock file used while a build runs |
The log records calls and results, not compiler output. A few lines from our lab after a PHP rebuild and a config rewrite:
2026-10-05 20:00:07 localhost: PHP 8.3.35 installed
2026-10-05 21:20:33 localhost: WP-CLI 2.12.0 installed
2026-10-05 21:20:44 localhost: called: php n
2026-10-05 21:36:00 localhost: called: rewrite_confs
2026-10-05 21:36:01 localhost: secure_phpini: /usr/local/php83/lib/php.ini securedA component that was called but never reports installed is your failed step. The actual error is in the compiler output, so run every build like this and keep the file:
cd /root
da build php 2>&1 | tee /root/cb-php-$(date +%F-%H%M).log
tail -n 60 /root/cb-php-*.logIf the build was started from the panel or a cron job and you did not capture its output, re-run the same component from SSH with tee to see the error again.
Is a build still running? The lock file
CustomBuild uses .custombuild.lock in its folder so two builds do not run at once. On our lab the file existed with size 0 while nothing was building, and fuser showed no process holding it. So the file being there is not, on its own, proof of a stuck build. Check for real build processes first:
cd /usr/local/directadmin/custombuild
ls -la .custombuild.lock
fuser -v .custombuild.lock # no output = no process holds it
ps -eo pid,etime,cmd | grep -E "[d]a build|[c]onfigure|[m]ake|[c]c1" If a build process is still running, let it finish; a PHP compile can take many minutes on a small VPS. If the process is hung for a long time (no CPU use, no change in output), stop it with kill PID, not kill -9, so it can clean up.
Only if no build process exists and a new build still refuses to start because of the lock, move the lock aside instead of deleting it: mv .custombuild.lock /root/custombuild.lock.$(date +%s). Then run one build and watch it. Never clear the lock while another build is running, or two builds will overwrite the same files.
Common compile errors and their fixes
The compiler was killed (out of memory)
Small VPSs run out of RAM while compiling PHP or MariaDB. The build stops with the compiler reported as killed, and the kernel log names the OOM killer:
dmesg -T | grep -iE "out of memory|oom-kill" | tail
free -mFix: stop memory-hungry services for the build window, or add temporary swap, then re-run the component.
No space left on device
df -h /usr/local /tmp /varOld source trees and tarballs pile up in the CustomBuild folder. da build clean removes old build data, and the clean=yes option (the default on our lab) does it after builds. da build clean_old_webapps removes old webmail and phpMyAdmin copies.
configure: error … not found
A configure script stops because a library or its headers are missing. The line names the library. Install the matching -devel package with dnf and re-run. On EL9 and EL10, some development packages live in the CRB repository, which must be enabled.
Errors from your own custom/ files
Files in custom/ override the stock ones in configure/. After an upgrade, a custom PHP configure file can carry flags the new PHP version removed, and the build fails on an option that no longer exists. Compare your file with the current stock one:
da build used_configs
diff /usr/local/directadmin/custombuild/configure/php/configure.php83 \
/usr/local/directadmin/custombuild/custom/php/configure.php83da build used_configs prints which file each component really uses. On our lab, with no custom/ folder, every path pointed into configure/, for example /usr/local/directadmin/custombuild/configure/php/configure.php83.
A third-party PHP extension does not build for a new PHP
Extensions such as ionCube or Phalcon may lag behind a new PHP release. Disable that extension for the new version (da build set php_ioncube no, for example) or stay on the older PHP until it is available.
Re-run only what failed
da build without arguments prints every target with a note when it is disabled by options.conf. Re-run the smallest target that covers the failure:
da build php 8.3 # one PHP version
da build php # all enabled PHP versions
da build php_extensions # all PHP extensions
da build apache
da build exim_conf # Exim configuration only
da build rewrite_confs # rewrite web server configsAvoid da build all as a fix. DirectAdmin’s own documentation says it is not recommended for regular use because it recompiles everything in use, which turns one failure into a long outage window.
Roll back to the previous version
CustomBuild installs what versions.txt lists. To stay on, or return to, an older release, add an override line to custom_versions.txt in the same name:version: format, then rebuild that component. Use the exact name as it appears in versions.txt; on our lab Apache is listed as apache2.4:2.4.69:. The cache/ folder keeps older source tarballs, which shows what ran before: our lab still had httpd-2.4.62 and httpd-2.4.65 through httpd-2.4.69.
cd /usr/local/directadmin/custombuild
cp -a options.conf /root/options.conf.$(date +%F)
grep -E "^apache2.4:" versions.txt
ls cache/ | grep httpd # versions you ran before
echo "apache2.4:2.4.68:" >> custom_versions.txt # pin the previous release
da build apache 2>&1 | tee /root/cb-apache-rollback.logRemove the line again once a fixed release is out, or the server stays on the old version for good. If a pin keeps getting undone, check for your own cron jobs that run CustomBuild updates.
Do not downgrade MariaDB across major versions with a pin. Data files upgraded by a newer major release may not open in an older one. With mysql_backup=yes (the default), CustomBuild dumps databases to mysql_backup_dir (/usr/local/directadmin/custombuild/mysql_backups on our lab) before a MariaDB update; restore from those dumps or from your own backups instead.
Check the database backup settings before any MariaDB build:
da build opt_help | grep -A0 -E "^mysql_backup"Check that it worked
da build versions | less # installed vs latest for each component
tail -n 20 /usr/local/directadmin/custombuild/custombuild.log
systemctl --failed- The rebuilt component shows the expected installed version in
da build versions. - The log has an installed line after your called line.
- Web, PHP-FPM, mail and database services are running, and a test site loads.
Official documentation: DirectAdmin: Upgrading services (CustomBuild) · DirectAdmin: Customize everything · DirectAdmin: Directories and locations
Related: DirectAdmin da CLI: update, build, config-set and More · CustomBuild PHP Versions: Switch PHP and Add Extensions Safely · Upgrade MariaDB DirectAdmin: Safe CustomBuild Path to 12.3 · DirectAdmin 503 PHP-FPM Errors: Log Checks · DirectAdmin license errors and update failures: da update, IP/hostname mismatches
See also: Migrate DirectAdmin to DirectAdmin: Move All Users to a New Server · Restore a File, Database or Account from a DirectAdmin Backup (CLI, Tested) · Force HTTPS for a Domain in DirectAdmin (Tested on 1.712)
Frequently asked questions
Where is the CustomBuild log in DirectAdmin?
The high-level log is /usr/local/directadmin/custombuild/custombuild.log. Compiler output goes to the terminal, so capture it with tee when you run da build.
Can I delete .custombuild.lock?
Only after you confirm no build process is running. Move it aside rather than deleting it, then run a single build and watch it.
How do I downgrade a component built by CustomBuild?
Add name:version: for the older release to custom_versions.txt and rebuild that component. Remove the line when you want updates again.
Should I run da build all after a failure?
No. Re-run only the failed component. DirectAdmin recommends against da build all for regular use.
Where does CustomBuild put database backups before a MariaDB update?
In mysql_backup_dir, which defaults to /usr/local/directadmin/custombuild/mysql_backups, when mysql_backup=yes.
Maintenance record
This guide changes servers, data or security settings, so we re-check it against current versions on a fixed schedule. Take a backup or snapshot before you start.
- Maintained by
- srvScripts editorial team
- Supported versions
- Tested on DirectAdmin 1.712 on AlmaLinux 9.8
- Last full review
- Next review