YunoHost App Install Troubleshooting – Post‑Install Hook, Nginx,

When a YunoHost app install fails, the culprit is often a mis‑configured post‑install hook, Nginx config, or Let’s Encrypt setup. This guide walks through symptoms, diagnostics, and fixes to get your app running again.

Recognizable Symptoms

When yunohost app install <app> exits with a non‑zero status, you’ll often see a message in /var/log/yunohost.log that looks like:

ERROR: postinstall script /usr/share/yunohost/apps/<app>/hooks/postinstall failed (exit code 1)

Common symptoms include:

The web UI shows the application as “Installation failed”.
Logs contain “permission denied” or “command not found” errors pointing to the hook directory.
SSL certificates are missing or the HTTPS URL redirects to HTTP.
Nginx reload fails with a syntax error that references a file in /etc/yunohost/apps/<app>/conf.

Underlying Causes

Cause	Typical Symptom
Non‑executable or mis‑owned hook scripts	"permission denied" in logs
Missing OS packages required by the hook	"command not found" during script execution
Corrupted or overwritten Nginx configuration	Nginx reload fails or HTTPS is not served
Let’s Encrypt DNS or rate‑limit problems	Certificate request fails, logs show “challenge failed”

Step‑by‑Step Diagnostics

Inspect the Yunohost log
```
sudo tail -n 50 /var/log/yunohost.log
```
Locate the first error after the install attempt. It usually references the hook that failed.
Verify hook script permissions
```
sudo ls -l /usr/share/yunohost/apps/<app>/hooks/*
```
All scripts should be owned by root:root and executable (-rwxr-xr-x). If any lack the x bit, add it:
```
sudo chmod 755 /usr/share/yunohost/apps/<app>/hooks/*
```
Run the failing hook manually
```
sudo /usr/share/yunohost/apps/<app>/hooks/postinstall
```
Observe any errors. If the script calls apt-get or dpkg, ensure the system is up‑to‑date:
```
sudo apt-get update && sudo apt-get upgrade -y
```
Validate Nginx configuration
```
sudo nginx -t -c /etc/nginx/nginx.conf
```
Look for syntax errors. If the test passes, reload Nginx:
```
sudo systemctl reload nginx
```
Check the app‑specific config at /etc/yunohost/apps/<app>/conf/nginx.conf for duplicate server_name directives or missing listen statements.
Confirm DNS and Let’s Encrypt setup
```
dig +short @8.8.8.8 <your-domain>
```
The IP returned must match the server’s public IP. Request a certificate manually:
```
sudo yunohost domain cert install <your-domain>
```
Check /var/log/yunohost.log for “challenge failed” or rate‑limit messages.

Fixes and Workarounds

Permission errors: Ensure hook scripts are root:root and executable.

sudo chown root:root /usr/share/yunohost/apps/<app>/hooks/*
sudo chmod 755 /usr/share/yunohost/apps/<app>/hooks/*

Missing dependencies: Install missing packages with apt. If the hook fails due to a missing command, run the command manually to verify, then install the package.
```
sudo apt-get install <missing-package>
```
Corrupted Nginx config: Re‑generate the app configuration with YunoHost.
```
sudo yunohost app regen-config <app>
sudo systemctl reload nginx
```
Let’s Encrypt rate limits or DNS issues: Verify that dig resolves to the correct IP. If rate‑limit errors appear, wait 24 hours or use the staging environment:
```
sudo yunohost domain cert install <your-domain> --staging
```

Escalation Criteria

If the install still fails after the above steps:

Check the YunoHost community forum for similar issues.
Open a ticket in the app’s GitHub repository; provide the log excerpt.
Run sudo yunohost tools diagnosis to surface system‑level problems.
Review the stack trace in /var/log/yunohost.log for a bug in the package itself.

Practical Verification

After applying a fix, re‑run the install command:

sudo yunohost app install <app>

Verify that the app appears in the Yunohost web UI and that https:// works. Re‑check Nginx with sudo nginx -t and confirm no syntax errors remain.

Diagnosing YunoHost App Install Failures: Post‑Install Hook, Nginx, and Let’s Encrypt Issues