manager/client-package/docs/09_TROUBLESHOOTING.md

Troubleshooting

Overview

Every error message the client can produce, with cause and fix. The messages come from manage-client/lib/.

Note: the client's actual messages are still German text (this is a German product), quoted verbatim in bold below. Each is followed by an italic English gloss and then an English explanation, so the heading itself stays searchable against what actually appears in your terminal or log.

First stop is always:

php manage-client/bin/manage-client.php status

and after that the log in MANAGE_LOG_FILE (default data/manage/manage-client.log, one JSON line per event):

tail -20 data/manage/manage-client.log | php -r 'while($l=fgets(STDIN)) { $e=json_decode($l,true); echo $e["timestamp"]," ",$e["level"]," ",$e["message"],"\n"; }'

Configuration and connection

Manage-Client ist nicht konfiguriert. MANAGE_SERVER_URL, MANAGE_INSTANCE und MANAGE_TOKEN müssen in manage-client/config.php gesetzt sein. ("The Manage client is not configured. MANAGE_SERVER_URL, MANAGE_INSTANCE and MANAGE_TOKEN must be set in manage-client/config.php.") config.php is missing, or one of the three values is empty. Copy config.sample.php and enter the values from the Manage server. Check that the file is really named manage-client/config.php.

Manage-Server ist nicht erreichbar: <URL> ("Manage server is unreachable: ") No response. Possible causes: wrong MANAGE_SERVER_URL, DNS, a firewall, outbound connections blocked by the host, an untrusted TLS certificate. Check with curl -v <URL>/api/v1/manifest.php from the same server.

Ungültige Server-URL: <URL> ("Invalid server URL: ") MANAGE_SERVER_URL isn't a valid URL. It must start with https:// and must contain neither /api nor a trailing slash.

Authentifizierung fehlgeschlagen. (HTTP 401) ("Authentication failed.") Instance id or token don't match. Both are deliberately indistinguishable. In the Manage server, under Instances, generate a new token and enter it; the old one becomes invalid immediately.

Diese Instanz ist deaktiviert. (HTTP 403) ("This instance is deactivated.") The instance exists but is deactivated in the Manage server. Reactivate it there.

Zu viele Anfragen. Bitte später erneut versuchen. (HTTP 429) ("Too many requests. Please try again later.") Too many failed authentications from this IP. Retry with the correct token after the time window expires (default 5 minutes).

Antwort des Servers ist kein gültiges JSON. ("The server's response is not valid JSON.") The response didn't come from the Manage server: usually a web server error page, a redirect, or a captive portal. Inspect the response directly with curl.

Update

Es ist kein neueres Update verfügbar. Mit der Option "force" kann dasselbe Paket erneut ausgerollt werden. ("No newer update is available. The "force" option can redeploy the same package.") Not an error. On the command line, update --force; in the UI, the "redeploy" checkbox.

Version im Manifest ist ungültig. / Prüfsumme im Manifest ist ungültig. / Paket-URL im Manifest ist ungültig. ("Version in the manifest is invalid." / "Checksum in the manifest is invalid." / "Package URL in the manifest is invalid.") The server returns an unusable manifest. On the server, check whether a release is published and set as current. For "package URL invalid", MANAGE_PUBLIC_URL in the server configuration is usually unset or wrong.

Größe des heruntergeladenen Pakets stimmt nicht überein. / Prüfsumme des Pakets stimmt nicht überein. ("Size of the downloaded package doesn't match." / "Checksum of the package doesn't match.") The package doesn't match the manifest. The downloaded file is deleted immediately and nothing is deployed. Causes: an interrupted download, a proxy that alters the content, or a package swapped out on the server. Re-upload the release and try again. If it keeps happening, check the transfer chain before deploying.

Das heruntergeladene Paket ist keine lesbare ZIP-Datei. ("The downloaded package is not a readable ZIP file.") The file is corrupted, or something other than a ZIP was uploaded.

Das Paket enthält einen unsicheren Pfad: <Pfad> ("The package contains an unsafe path: ") An entry tries to break out of the target directory (.., an absolute path, a drive letter, a null byte). Nothing gets extracted. Such a package must not be deployed — find out where it came from.

Das Paket sieht nicht wie ein Release dieser Anwendung aus (erwartet: index.php) ("The package doesn't look like a release of this application (expected: index.php)") None of the paths from MANAGE_UPDATE_SANITY_PATHS is in the package. Almost always the ZIP was built with a top-level directory. See 06_UPDATE_PACKAGING.

Die PHP-Erweiterung ZipArchive ist nicht verfügbar. ("The PHP ZipArchive extension is not available.") ext-zip is missing. Updates need it; backups still work without it, because the client uses its own ZIP writer there. Have the host enable it.

Datei konnte nicht ausgerollt werden: <Pfad> / Datei konnte nicht gesichert werden: <Pfad> ("File could not be deployed: " / "File could not be backed up: ") Missing write permission in the application root. Important: this error occurs mid-run, so the deployment is then incomplete. Fix permissions and run update --force again — the run starts over and restores the complete state.

Verzeichnis konnte nicht erstellt werden: <Pfad> ("Directory could not be created: ") Missing write permission on the parent directory.

Altes Backup-Verzeichnis konnte nicht entfernt werden: <Pfad> ("Old backup directory could not be removed: ") Deployment succeeded; only cleaning up old backups failed. Remove the directory by hand.

MANAGE_APP_ROOT existiert nicht: <Pfad> ("MANAGE_APP_ROOT does not exist: ") The configured application root is wrong. The default is the parent directory of manage-client/.

Migrations and hook

Migration <id> liefert keine Funktion zurück und definiert kein up(). ("Migration does not return a function and does not define up().") The migration file must either return a function (return function (array $context) {...};) or define a function up(array $context).

A migration fails with its own error The run stops, the following migrations stay pending, but the files are already deployed. Fix the cause, then:

php manage-client/bin/manage-client.php migrate --dry-run
php manage-client/bin/manage-client.php migrate

Hook-Datei wurde nicht gefunden: <Pfad> / Hook-Callback ist nicht aufrufbar: <Name> ("Hook file was not found: " / "Hook callback is not callable: ") MANAGE_UPDATE_POST_HOOK points to a missing file, or a function that isn't defined there. Common when the hook file isn't in the release package.

Post-Update-Hook meldet einen Fehler ("Post-update hook reports an error") The callback returned false or ["success" => false]. The files are deployed; the details are in the log.

Backup

Es läuft bereits ein Backup. ("A backup is already running.") The lock file is held: a second run started while the first was still going. Usually a cron job and a manual run overlap. Wait and retry. If it persists, an earlier run was killed hard — the lock releases itself when that process ends; if that doesn't help, remove data/manage/backups/.backup.lock once you're certain no backup is running.

Keine Dateien für das Backup gefunden. / Keine lesbaren Dateien für das Backup gefunden. ("No files found for the backup." / "No readable files found for the backup.") MANAGE_BACKUP_SOURCES matches no existing file. Paths are relative to MANAGE_APP_ROOT. Check with:

php -r 'require "manage-client/lib/client.php"; print_r(manageBackupCollectSources());'

Backup-ZIP konnte nicht erstellt werden. / Backup-ZIP konnte nicht finalisiert werden. ("Backup ZIP could not be created." / "Backup ZIP could not be finalized.") No write access to MANAGE_BACKUP_DIR, or the disk is full.

Datei ist zu groß für dieses Backup-Format: <Name> / Backup-ZIP ist zu groß für dieses Backup-Format. / Zu viele Dateien für dieses Backup-Format. ("File is too large for this backup format: " / "Backup ZIP is too large for this backup format." / "Too many files for this backup format.") Limits of the ZIP format without Zip64: 4 GB per file, 4 GB per archive, 65535 entries. Split up the sources, or back up large media files separately.

Ungültiger Pfad im Backup: <Name> / Pfad im Backup ist zu lang: <Name> ("Invalid path in the backup: " / "Path in the backup is too long: ") A filename contains invalid characters, or the as prefix produces an invalid archive path. Use prefixes without a leading slash and without ...

Der Manage-Server hat das Backup abgelehnt: Ungültiger Backup-Dateiname. ("The Manage server rejected the backup: invalid backup filename.") The filename doesn't match backup-YYYYmmdd-HHMMSS[-N].zip. Only happens with self-built uploads.

Der Manage-Server hat das Backup abgelehnt: Prüfsumme des Backups stimmt nicht überein. ("The Manage server rejected the backup: backup checksum doesn't match.") The archive was altered in transit, or transferred incompletely. The file is deleted server-side. The local archive is fine; try again.

Backup überschreitet das Upload-Limit des Servers (upload_max_filesize / post_max_size). ("Backup exceeds the server's upload limit (upload_max_filesize / post_max_size).") The PHP limits on the Manage server are smaller than the archive. Increase upload_max_filesize and post_max_size there (both!), or reduce the backup's scope. The current values are shown in the Manage server under Settings → Diagnostics.

The upload failure does not invalidate the local archive — it sits complete in data/manage/backups/.

Database

Die PHP-PDO-Erweiterung ist nicht verfügbar. ("The PHP PDO extension is not available.") pdo_mysql is missing. No dump can be created without it; set MANAGE_BACKUP_DATABASE to null or have the extension enabled.

Datenbankverbindung fehlgeschlagen: <Meldung> ("Database connection failed: ") DSN, user or password are wrong, or the server is unreachable. PDO's original message follows.

MANAGE_BACKUP_DATABASE benötigt einen DSN. ("MANAGE_BACKUP_DATABASE requires a DSN.") The array is set, but dsn is missing or empty.

Datenbank-Dump fehlgeschlagen: <Meldung> ("Database dump failed: ") Usually missing permissions: the user needs SELECT and SHOW VIEW on all tables. The incomplete dump is deleted; the backup aborts.

Extra targets

Die PHP-SSH2-Erweiterung ist nicht verfügbar. ("The PHP SSH2 extension is not available.") SFTP needs ext-ssh2. Without it, only this target fails; the local archive and every other target are unaffected.

SFTP-Zieldatei konnte nicht geöffnet werden. Existiert das Verzeichnis? ("SFTP target file could not be opened. Does the directory exist?") The remote directory must exist and be writable; it isn't created.

S3-Ziel ist unvollständig konfiguriert. ("S3 target is incompletely configured.") bucket, region, access_key and secret_key are all required.

S3-Upload fehlgeschlagen (HTTP 403) ("S3 upload failed (HTTP 403)") With SignatureDoesNotMatch, region or secret key are wrong. With AccessDenied, the addressing style is usually wrong — set endpoint for S3-compatible providers.

Unbekannter Backup-Zieltyp: <typ> ("Unknown backup target type: ") type must be s3, sftp or custom. The earlier type managed is gone: the upload to the Manage server is built in and controlled via MANAGE_BACKUP_UPLOAD.

Permissions at a glance

# Check PHP write access
php -r '
foreach (["data/manage/backups", "data/manage/work", "data/manage/updates", "."] as $d) {
    printf("%-26s %s\n", $d, is_writable($d) ? "writable" : "NOT writable");
}'

The last entry, ., is the application root — without write access there, no updates are possible.

Next

• 03_CONFIG_REFERENCE – every constant
• 08_PROTOCOL – reproducing requests with curl