Skip to content

Troubleshooting

Common issues and their solutions.

Table of Contents

Installation Issues

Wizard does not load

Symptom: Accessing WebCalendar shows a blank page or error instead of the installation wizard.

Solutions:

  1. Verify PHP is working: create a phpinfo.php with <?php phpinfo(); and load it in your browser.
  2. Check that the includes/ directory is writable by the web server (the wizard needs to create settings.php).
  3. Check PHP error logs for specific errors.

"Permission denied" writing settings.php

The web server user needs write access to the includes/ directory during installation:

chmod 775 /path/to/webcalendar/includes
chown www-data:www-data /path/to/webcalendar/includes

After installation, tighten permissions:

chmod 755 /path/to/webcalendar/includes
chmod 600 /path/to/webcalendar/includes/settings.php

Database connection fails in wizard

  • Verify the database server is running.
  • Verify the hostname, username, password, and database name.
  • Check that the PHP database extension is loaded (mysqli, pgsql, etc.): php -m | grep -i mysql
  • For MySQL: verify the user has CREATE TABLE permissions.

Database Issues

"Table doesn't exist" errors

If tables are missing after an upgrade, re-run the wizard:

https://yourserver.com/webcalendar/wizard/index.php

The wizard detects the current schema version and applies missing updates.

Database connection drops

  • Check $db_persistent in includes/settings.php — try toggling it.
  • For MySQL: increase wait_timeout and max_connections.
  • For PostgreSQL: check max_connections in postgresql.conf.

Specific Errors

  • "Error removing temporary file" or "Cache error": Indicates a file in the database cache directory could not be modified. This often happens when the reminder cron job runs under a different system account than the web server, causing ownership conflicts. Ensure both accounts have write permissions to $db_cachedir.
  • "Failed opening 'includes/...' for inclusion": You may need to modify the include_path in your php.ini. Add the WebCalendar base directory to the list.
  • "Call to undefined function": Your PHP installation is missing a required module (e.g., mysqli_connect). Verify all Requirements are met.
  • "Can't connect to local MySQL server through socket '/tmp/mysql.sock'": The value of mysql.default_socket in php.ini must match the actual socket location used by your MySQL server (check my.cnf).
  • "Client does not support authentication protocol": This typically occurs when an older PHP MySQL client attempts to connect to a newer MySQL/MariaDB server using the old hashing algorithm. Update your PHP extensions or re-hash the database password using the new algorithm.

Authentication Issues

Cannot log in after installation

  • Verify the admin user was created during the wizard setup.
  • Check that $user_inc in includes/settings.php matches your auth method (default: user.php for database auth).
  • Reset the password from the command line:
php bin/webcal.php user reset-password --login=admin

The new password is printed once. See Command Line for the options, including reading the password from standard input instead of having one generated.

Resetting it with SQL still works, because a 32-character hexadecimal cal_passwd is read as a legacy MD5 hash and re-hashed on the next successful login:

UPDATE webcal_user
SET cal_passwd = MD5('newpassword')
WHERE cal_login = 'admin';

Prefer the command where you can. The SQL leaves an unsalted MD5 hash in the table until that next login, and anyone able to read webcal_user in the meantime can reverse it.

LDAP login fails

  • Verify LDAP server is reachable from the web server.
  • Check LDAP connection settings in includes/settings.php.
  • Test with ldapsearch from the command line.
  • Ensure PHP ldap extension is loaded: php -m | grep ldap

HTTP authentication not working

  • PHP must be running as an Apache module (not CGI/FPM) for $_SERVER['PHP_AUTH_USER'] to be available.
  • Set $use_http_auth = true in includes/settings.php.
  • Configure Apache with AuthType Basic or your preferred method.

Display Issues

Events show at wrong times

  1. Check your timezone in Preferences.
  2. Check date.timezone in php.ini: 
    php -r "echo ini_get('date.timezone');"
  3. Verify the database stores times in GMT (standard since v1.1).

Calendar layout is broken

  • Clear your browser cache.
  • Verify CSS files are accessible: check the browser console for 404 errors on files in includes/css/ or pub/.
  • If using a reverse proxy, ensure it passes static assets correctly.

Characters display incorrectly (mojibake)

  • Verify your database uses UTF-8 encoding.
  • Check that php.ini has default_charset = "UTF-8".
  • For MySQL: verify character_set_server = utf8mb4.

Email Issues

Reminders not being sent

  1. Verify the cron job exists and runs: 
    crontab -l | grep send_reminders
  2. Test email manually: 
    php bin/webcal.php email test --to=you@example.com
  3. Check that SEND_EMAIL is Y in admin settings.
  4. Check PHP error log for mail delivery errors.

Email shows as spam

  • Configure SPF, DKIM, and DMARC records for your sending domain.
  • Use authenticated SMTP rather than PHP's mail() function.
  • Set a valid From: address in admin email settings.

Performance Issues

Pages load slowly

  • Enable PHP opcode caching (OPcache).
  • Enable database query caching ($db_cachedir in settings).
  • Check database performance (add indexes, optimize tables).
  • For MySQL: tune innodb_buffer_pool_size.

High memory usage

  • Reduce memory_limit if set too high.
  • If displaying many events, add date range limits to views.
  • Consider PostgreSQL or MySQL instead of SQLite for large datasets.

Docker Issues

Container exits immediately

Check container logs:

docker-compose -f docker/docker-compose-prod.yml logs

Common causes:

  • Database container not ready — the app may start before the DB. Restart the app container if this happens.
  • Port conflict — another service is using port 8080.

Changes not reflected in dev mode

Verify the volume mount is correct in your docker-compose file. Dev configurations should mount the local directory into the container.

Cannot connect to database from app container

  • Verify the database service name matches WEBCALENDAR_DB_HOST.
  • Wait for the database container to be fully started.
  • Check that the database credentials match between services.

Diagnostic Steps

Collect everything at once

php bin/webcal.php diagnose           # human readable
php bin/webcal.php diagnose --json    # machine readable

This reports the WebCalendar and PHP versions, the extensions WebCalendar uses, the database type and server version, directory writability, and the configuration settings that usually matter, in one block you can paste into a bug report.

It works when the calendar does not. A missing or broken includes/settings.php produces a report rather than a redirect to the installation wizard, which is the situation you most need it in.

It is safe to post publicly. Passwords, API tokens, host names and email addresses are reported only as (set) or (not set), and any setting that has not been explicitly classified is left out and counted rather than printed. If you would rather check first, read it before pasting — that is the point of the human-readable form.

Administrators who can still log in can get the same report with a copy button under Admin > Security Audit > Diagnostic report.

The individual checks below are still useful when you want to look at one thing in isolation, or when you cannot run the command at all.

Check PHP configuration

php -v              # PHP version
php -m              # Loaded extensions
php -i | grep -i timezone  # Timezone setting

Check file permissions

ls -la includes/settings.php
ls -la includes/

Check database connectivity

# MySQL
mysql -u webcalendar -p -h localhost webcalendar -e "SELECT 1"

# PostgreSQL
psql -U webcalendar -h localhost webcalendar -c "SELECT 1"

Check error logs

# Apache
tail -f /var/log/apache2/error.log

# Nginx + PHP-FPM
tail -f /var/log/nginx/error.log
tail -f /var/log/php-fpm/error.log

# Docker
docker-compose logs -f

Run PHP syntax check

cd /path/to/webcalendar
tests/compile_test.sh