# 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:

```bash
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):

```bash
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: <URL>")*
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: <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: <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](06_UPDATE_PACKAGING.md).

**`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: <path>" / "File could not be backed up:
<path>")*
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: <path>")*
Missing write permission on the parent directory.

**`Altes Backup-Verzeichnis konnte nicht entfernt werden: <Pfad>`** *("Old
backup directory could not be removed: <path>")*
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: <path>")*
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 <id> 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:

```bash
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: <path>" / "Hook callback is not callable:
<name>")*
`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:

```bash
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: <name>" / "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: <name>" / "Path in the backup is too long:
<name>")*
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: <message>")*
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:
<message>")*
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>")*
`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

```bash
# 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](03_CONFIG_REFERENCE.md) – every constant
- [08_PROTOCOL](08_PROTOCOL.md) – reproducing requests with `curl`