::: {.warning}
    Don't delete {file}`config.php`! This file
    tracks the application's state and a deletion can cause unwanted
    side-effects!
    :::

    ::: {.warning}
    Don't rerun `nextcloud-occ maintenance:install`!
    This command tries to install the application
    and can cause unwanted side-effects!
    :::
  - **Multiple version upgrades.**
    Nextcloud doesn't allow to move more than one major-version forward. E.g., if you're on
    `v16`, you cannot upgrade to `v18`, you need to upgrade to
    `v17` first. This is ensured automatically as long as the
    [stateVersion](#opt-system.stateVersion) is declared properly. In that case
    the oldest version available (one major behind the one from the previous NixOS
    release) will be selected by default and the module will generate a warning that reminds
    the user to upgrade to latest Nextcloud *after* that deploy.
  - **`Error: Command "upgrade" is not defined.`**
    This error usually occurs if the initial installation
    ({command}`nextcloud-occ maintenance:install`) has failed. After that, the application
    is not installed, but the upgrade is attempted to be executed. Further context can
    be found in [NixOS/nixpkgs#111175](https://github.com/NixOS/nixpkgs/issues/111175).

    First of all, it makes sense to find out what went wrong by looking at the logs
    of the installation via {command}`journalctl -u nextcloud-setup` and try to fix
    the underlying issue.

    - If this occurs on an *existing* setup, this is most likely because
      the maintenance mode is active. It can be deactivated by running
      {command}`nextcloud-occ maintenance:mode --off`. It's advisable though to
      check the logs first on why the maintenance mode was activated.
    - ::: {.warning}
      Only perform the following measures on
      *freshly installed instances!*
      :::

      A re-run of the installer can be forced by *deleting*
      {file}`/var/lib/nextcloud/config/config.php`. This is the only time
      advisable because the fresh install doesn't have any state that can be lost.
      In case that doesn't help, an entire re-creation can be forced via
      {command}`rm -rf ~nextcloud/`.

  - **Server-side encryption.**
    Nextcloud supports [server-side encryption (SSE)](https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/encryption_configuration.html).
    This is not an end-to-end encryption, but can be used to encrypt files that will be persisted
    to external storage such as S3.

  - **Issues with file permissions / unsafe path transitions**

    {manpage}`systemd-tmpfiles(8)` makes sure that the paths for

    * configuration (including declarative config)
    * data
    * app store
    * home directory itself (usually `/var/lib/nextcloud`)

    are properly set up. However, `systemd-tmpfiles` will refuse to do so
    if it detects an unsafe path transition, i.e. creating files/directories
    within a directory that is neither owned by `root` nor by `nextcloud`, the
    owning user of the files/directories to be created.

    Symptoms of that include

    * `config/override.config.php` not being updated (and the config file
      eventually being garbage-collected).
    * failure to read from application data.

    To work around that, please make sure that all directories in question
    are owned by `nextcloud:nextcloud`.

  - **`Failed to open stream: No such file or directory` after deploys**

    Symptoms are errors like this after a deployment that disappear after
    a few minutes:

    ```
    Warning: file_get_contents(/run/secrets/nextcloud_db_password): Failed to open stream: No such file or directory in /nix/store/lqw657xbh6h67ccv9cgv104qhcs1i2vw-nextcloud-config.php on line 11

    Warning: http_response_code(): Cannot set response code - headers already sent (output started at /nix/store/lqw657xbh6h67ccv9cgv104qhcs1i2vw-nextcloud-config.php:11) in /nix/store/ikxpaq7kjdhpr4w7cgl1n28kc2gvlhg6-nextcloud-29.0.7/lib/base.php on line 639