Resolving 'Application Not Found' and 404 Errors in YunoHost

The Routing Failure Problem

When accessing a YunoHost-hosted application, a 404 "Not Found" or "Application Not Found" error usually indicates a breakdown in the reverse proxy chain. In YunoHost, Nginx acts as the traffic controller; it reads the incoming HTTP Host header (the domain name used in the browser) and routes the request to the correct internal service. If Nginx cannot map that domain to a specific application instance, it serves a default 404 page, even if the application is running perfectly in the background.

Diagnostic Matrix

Use this table to identify the most likely cause based on the observed behavior.

Symptom	Likely Cause	Diagnostic Focus
404 on a newly added domain	Missing domain association	YunoHost Domain Database
404 only on specific sub-paths	App-level routing error	Application Logs
Generic Nginx 404 on all domains	Nginx configuration corruption	Nginx Error Logs
Connection Timeout (not 404)	DNS or Firewall issue	External DNS Records

Step-by-Step Diagnostic Workflow

Perform these checks in order. All commands must be run via SSH as a user with sudo privileges or as the root user.

1. Verify Application Status

First, determine if the application is actually running. A routing error is different from a service crash.

yunohost app list

Expected Result: The application should be listed as "installed". If the app is missing or marked as failed, the issue is with the installation, not the Nginx routing.

2. Check Domain Mapping

Verify if the domain you are using is correctly associated with the application.

yunohost domain list

Look for the domain in question. If the domain is listed but not linked to the specific application, Nginx will not know where to send the traffic.

3. Inspect Nginx Error Logs

If the domain mapping looks correct, check the Nginx logs to see if the request is reaching the server and where it is failing.

tail -f /var/log/nginx/error.log

What to look for: Look for "no such file or directory" or "upstream timed out". If you see no entries when refreshing the page, the request is likely being blocked by a firewall or failing at the DNS level before reaching Nginx.

Applying the Fixes

Scenario A: Domain is not associated with the App

If yunohost domain list shows the domain exists but isn't linked to the app, you must manually associate them. This tells YunoHost to generate the necessary Nginx server blocks.

yunohost domain associate [domain_name] [app_name]

Example: To link blog.example.com to a WordPress installation named wordpress:
yunohost domain associate blog.example.com wordpress

Scenario B: Configuration Desync

Sometimes the database is correct, but the Nginx config files are out of sync. Force a refresh of the Nginx configuration.

yunohost service restart nginx

Limitations and Risks

• Manual Config Overwrites: Do not manually edit files in /etc/nginx/. YunoHost uses automated templates; any manual changes will be overwritten the next time you update an app or change a domain setting.
• Primary Domain Conflicts: Avoid associating multiple domains as "primary" for a single application unless the application explicitly supports multi-tenancy, as this can cause redirect loops.

Verification of Resolution

To confirm the fix, run the following check to ensure the domain is now correctly mapped in the system:

yunohost domain list | grep [your_domain]

Then, attempt to access the site using a private browser window to bypass cached 404 responses.

Escalation Criteria

If the following conditions persist, the issue is beyond simple routing and requires deeper system investigation:

• The yunohost domain associate command returns a success message, but the 404 persists after an Nginx restart.
• Nginx logs show "Permission Denied" errors relating to the www-data user.
• The server is unreachable via IP address, indicating a network-level failure rather than a YunoHost configuration issue.