Fix or report cases where Nginx configuration regeneration fails, Nginx cannot restart, or a site stays offline after domain, SSL, Docker, redirect, or rule changes.

Symptoms #

Use this guide if you see one or more of these issues:

• The site is offline after changing domain, SSL, redirects, headers, Docker, or proxy settings.
• The dashboard shows an Nginx regeneration or restart failure.
• A custom app or Docker app cannot finish Nginx setup.
• A site returns 500 because cache, proxy, or vhost files are invalid or inaccessible.
• Nginx cannot start after a configuration update.

Before you start #

• Confirm you are signed in to the correct xCloud team.
• Open the related Server, Site, Billing, Team, or Settings page in your xCloud dashboard.
• Keep a copy of the exact error message before retrying.
• If the issue affects a live production site, avoid repeated risky changes until you understand the cause.

Step-by-step troubleshooting #

1. Open the latest failed event #

1. Go to the affected Server in xCloud.
2. Open Events or the site-level event history.
3. Find the most recent failed event related to Regenerate Nginx Config, Restart Nginx, Deploy SSL, or Create Site.
4. Open the event output and copy the exact error text.

(Screenshot: open the latest failed event in xCloud.)

2. Check recent setting changes #

1. Review changes made before the failure: domain update, redirect rule, custom header, SSL retry, Docker/Compose deployment, port change, or custom Nginx rule.
2. If the issue started after adding a rule, temporarily remove the new rule if the dashboard allows it safely.
3. Avoid editing server-level Nginx files manually unless you understand the impact.

3. Review site logs and cache state #

1. Open the site Logs page and check Nginx error logs.
2. Look for permission denied, missing file, duplicate directive, invalid directive, unsupported HTTP/3/QUIC directive, or upstream connection errors.
3. If the issue appears cache-related, disable page/FastCGI cache temporarily only as a recovery step, then report the root cause.

4. Retry only after correcting the visible cause #

1. After fixing DNS, SSL, redirect, or unsupported setting issues, retry the failed action once.
2. If the same event fails again, stop retrying and contact support with the event output.
3. For production sites, avoid repeated regenerate/restart attempts during high-traffic periods.

What xCloud Support can check #

• Inspect failed event output and Nginx error logs.
• Check whether generated config files, redirect/header files, cache ownership, or proxy rules are missing or invalid.
• Regenerate supported xCloud configuration when the cause is platform-generated config.
• Escalate product bugs or unsupported directives to engineering.

What to send xCloud Support #

• Server and site name.
• The exact dashboard event name and error output.
• What changed immediately before the failure.
• Whether the site is WordPress, custom PHP, Docker, Node.js, or another app type.
• Screenshots of the failed event and current domain/SSL/proxy settings.

Prevention tips #

• Make one Nginx-related change at a time and verify the site before changing more.
• Avoid unsupported custom Nginx directives unless confirmed by support.
• Keep custom redirects and headers simple.
• Check Docker/custom-app ports before connecting them through the proxy.

How to understand the error #

Nginx regeneration is a validation step. xCloud builds the server configuration for the site, tests whether Nginx accepts it, and then restarts or reloads the service. If any generated or custom rule is invalid, Nginx may reject the entire configuration to avoid loading a broken web server. This can happen after domain changes, SSL retries, redirect/header changes, Docker proxy updates, custom app ports, or unsupported directives. The exact event output matters because “Nginx failed” is only the final symptom. The useful clue is usually the missing file, duplicate directive, invalid directive, permission issue, or upstream/port error shown inside the event or log.

Expected result #

After troubleshooting, you should be able to confirm one of these outcomes:

• The issue is resolved and the related site, server, billing item, integration, or team access works as expected.
• The dashboard shows a clear error that can be shared with xCloud Support.
• The issue is outside xCloud platform support and needs action from your developer, DNS provider, payment gateway, software vendor, or third-party service provider.

If the issue affects production, verify the public site and the xCloud dashboard after every major change. Keep screenshots of the before-and-after state so support can understand what changed.

When to contact support immediately #

Contact xCloud Support before continuing if:

• The issue affects a live production site or active customer portal.
• A server, database, billing item, or team owner setting may be permanently changed or deleted.
• You see repeated failures after one careful retry.
• You are unsure whether a root-level, database-level, DNS, or billing action is safe.

FAQ #

Can I edit Nginx files directly over SSH? #

xCloud provides full root access and the root password where applicable, but direct Nginx edits can break future dashboard regeneration. For security, use SSH key-based login instead of password login and contact xCloud Support before risky production changes.

Why did SSL or Docker setup fail with an Nginx error? #

SSL, Docker, custom apps, redirects, and domains all depend on valid Nginx configuration. A failure in one generated block can prevent Nginx from restarting.

Should I keep retrying the regenerate button? #

Retry once after correcting the visible cause. If it fails again, send support the event output instead of repeatedly restarting Nginx.