Troubleshooting#

This page covers common issues and their solutions. For job-specific debugging, see Debugging Failed Jobs.

Quick Diagnostics#

Run these checks first when something is wrong:

# Service status
systemctl status multiflexi-scheduler multiflexi-executor multiflexi-eventor

# Recent executor errors
sudo journalctl -u multiflexi-executor -n 50 --no-pager

# Recent scheduler errors
sudo journalctl -u multiflexi-scheduler -n 50 --no-pager

# Web server errors
sudo tail -20 /var/log/apache2/error.log

# Application log
sudo tail -20 /var/log/multiflexi/multiflexi.log

Authentication Issues#

Invalid Security Token#

Symptom: “Invalid security token.” error when logging in.

Cause: CSRF token mismatch — usually a stale session or browser cache issue.

Solutions:

  1. Clear browser cookies and cache for the MultiFlexi domain

  2. Try an incognito/private browser window

  3. Verify PHP session storage is writable:

    ls -la $(php -r "echo session_save_path();")
# Should be writable by the web server user (www-data)

  4. Restart PHP-FPM and web server:

    sudo systemctl restart php8.2-fpm apache2

  5. Check server time synchronization:

    timedatectl status

Sessions Expire Much Sooner Than SESSION_TIMEOUT#

Symptom: Users are silently logged out after ~20-30 minutes of inactivity, well short of the SESSION_TIMEOUT configured in /etc/multiflexi/multiflexi.env (default 14400s / 4h). No “Your session has expired” message is shown - the user just appears logged out, and a DataTables view being polled in the background (e.g. the Jobs list) may briefly show an “Invalid JSON response” warning if this happens mid-poll.

Cause: on Debian/Ubuntu, PHP session files under session.save_path (default /var/lib/php/sessions) are reaped by an OS-level housekeeper independent of the application - either a cron job (/etc/cron.d/php) or, on systemd hosts, the phpsessionclean.timer / phpsessionclean.service pair (check which is active with systemctl list-timers | grep sess). Both read session.gc_maxlifetime directly from the PHP-FPM pool’s on-disk php.ini - Debian’s stock default is 1440 seconds (24 minutes). MultiFlexi’s own SessionManager calls ini_set('session.gc_maxlifetime', ...) with the configured SESSION_TIMEOUT, but that only affects the current PHP-FPM worker process for the current request - it never reaches the static php.ini that the standalone cleanup script parses. So whichever value is smaller wins in practice, and on a stock Debian/Ubuntu PHP-FPM pool that’s almost always the 24-minute system default, not the app’s own timeout.

Because the session file simply disappears (rather than the app detecting an expired/invalid session), session.use_strict_mode (which MultiFlexi does set) causes PHP to silently start a brand-new, empty session instead of erroring - so the app’s own “session expired, redirecting to login” flow never triggers for this case, and the logout happens with no warning.

Solutions:

  1. Check what the PHP-FPM pool serving MultiFlexi actually has configured:

    php -i | grep -i gc_maxlifetime
systemctl list-timers | grep sess

  2. Give MultiFlexi its own PHP-FPM pool (recommended if it shares the default www pool with other applications) with php_admin_value[session.gc_maxlifetime] = <SESSION_TIMEOUT seconds>, matching the value configured in /etc/multiflexi/multiflexi.env. This is the only way to make the pool-wide setting - and therefore what the cleanup timer reads - match the app’s intended timeout without affecting other applications sharing the default pool.

  3. Alternatively, raise session.gc_maxlifetime in the shared pool’s php.ini directly, accepting that this also extends session lifetime for any other application sharing that pool.

Cannot Log In (Wrong Password)#

If you forget the administrator password, reset it via CLI:

multiflexi-cli user update --login=admin --password=newpassword

Jobs Not Running#

Jobs Stay in “Pending” State#

Cause: Executor daemon is not running.

systemctl status multiflexi-executor
sudo systemctl start multiflexi-executor

If it keeps failing to start:

sudo journalctl -u multiflexi-executor -n 100
# Look for "PHP Fatal error" or "Connection refused"

No New Jobs Being Created#

Cause: Scheduler daemon is not running, or all RunTemplates are inactive.

systemctl status multiflexi-scheduler
multiflexi-cli run-template:list  # check Active column

Job Fails Immediately (exit code non-zero)#

  1. Open the job in the web interface → Artifacts → read stderr.txt

  2. Check that the application package is installed:

    dpkg -l | grep <app-name>

  3. Run the application manually with the same environment:

    multiflexi-cli run-template:get --id=<ID> --export | bash -c 'eval "$(cat)" && <executable>'

See Debugging Failed Jobs for a complete walkthrough.

Job Runs Forever / Never Finishes#

Cause: Usually the application hangs waiting for input, or the executor hit its memory ceiling (2 GB) and restarted.

# Check for zombie processes
ps aux | grep multiflexi

# Check memory usage
sudo journalctl -u multiflexi-executor | grep -i memory

# Check if executor restarted
sudo journalctl -u multiflexi-executor | grep "Started\|Stopped"

Credential Issues#

Credential Fields Not Passed to Job#

Cause: The CredentialType is not assigned to the RunTemplate.

multiflexi-cli run-template:list-credentials --id=<ID>
# If empty, assign the credential:
multiflexi-cli run-template:assign-credential --id=<ID> --credentialtype=<ID>

Wrong Values in Credentials#

# Show current values
multiflexi-cli credential-type:get --id=<ID>

# Update
multiflexi-cli credential-type:update --id=<ID> --FIELD_NAME=newvalue

Installation Issues#

APT Repository Not Found#

# Re-add the repository
sudo curl -fsSL https://repo.multiflexi.eu/KEY.gpg \
  -o /usr/share/keyrings/multiflexi-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/multiflexi-archive-keyring.gpg] \
  https://repo.multiflexi.eu/ $(lsb_release -sc) main" | \
  sudo tee /etc/apt/sources.list.d/multiflexi.list
sudo apt update

Database Migration Fails During Install#

# Check database connectivity
mysql -u multiflexi -p -h 127.0.0.1 multiflexi -e "SHOW TABLES;"

# Run migrations manually
sudo -u multiflexi php /usr/share/multiflexi/vendor/bin/phinx migrate \
  -c /etc/multiflexi/phinx.php

Web Interface Issues#

White Screen / HTTP 500#

sudo tail -50 /var/log/apache2/error.log
sudo tail -50 /var/log/multiflexi/multiflexi.log

# Enable debug mode temporarily
echo "APP_DEBUG=true" | sudo tee -a /etc/multiflexi/multiflexi.env
sudo systemctl reload apache2

# Revert after fixing
sudo sed -i '/APP_DEBUG=true/d' /etc/multiflexi/multiflexi.env

Page Not Found (404) for /multiflexi#

# Ensure mod_rewrite is enabled
sudo a2enmod rewrite
sudo systemctl restart apache2

# Check Apache site configuration
sudo cat /etc/apache2/conf-available/multiflexi.conf

Slow Performance#

# Check database query performance
mysql -u root -p multiflexi -e "SHOW PROCESSLIST;"

# Optimize heavy tables
mysql -u root -p multiflexi -e "OPTIMIZE TABLE job, artifacts, logger;"

# Purge old job data
multiflexi-cli job cleanup --older-than=90

Docker Deployment Issues#

Container Cannot Reach Database#

# Check service health in Docker Compose
docker compose ps

# Test database connectivity from web container
docker compose exec web mysql -u multiflexi -p -h db multiflexi -e "SHOW TABLES;"

Container Keeps Restarting#

docker compose logs executor
docker compose logs scheduler

See Docker Deployment for full Docker troubleshooting.

Zabbix Integration Issues#

Metrics Not Appearing in Zabbix#

  1. Verify the Zabbix sender configuration:

    grep ZABBIX /etc/multiflexi/multiflexi.env

  2. Test connectivity to the Zabbix server:

    nc -zv <ZABBIX_SERVER> 10051

  3. Check that the MultiFlexi host exists in Zabbix and has the template applied.

See Zabbix Integration for setup details.

Getting Help#

If none of the above resolves your issue:

  1. Check the GitHub Issues for known bugs

  2. Review the full documentation at https://multiflexi.readthedocs.io/

  3. Open a new GitHub issue with: - MultiFlexi version: dpkg -l multiflexi - OS and PHP version: lsb_release -a && php -v - Relevant log output - Steps to reproduce

See Also#