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:

Clear browser cookies and cache for the MultiFlexi domain
Try an incognito/private browser window

Verify PHP session storage is writable:

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

Restart PHP-FPM and web server:

sudo systemctl restart php8.2-fpm apache2

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:

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

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

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.
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)¶

Open the job in the web interface → Artifacts → read stderr.txt
Check that the application package is installed:
```
dpkg -l | grep <app-name>
```

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 ¶

Verify the Zabbix sender configuration:

grep ZABBIX /etc/multiflexi/multiflexi.env

Test connectivity to the Zabbix server:
```
nc -zv <ZABBIX_SERVER> 10051
```
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:

Check the GitHub Issues for known bugs
Review the full documentation at https://multiflexi.readthedocs.io/
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