Troubleshooting

Troubleshooting, Logs and FAQs

Solutions for common build failures, deployment quirks, and environment issues.

Troubleshooting Build Errors

You can troubleshoot build errors that occur during the Build step of your deployment to Lynfera. This guide will help you understand how to investigate build failures and long build times.

Troubleshooting views

You can use the following views on your dashboard to troubleshoot a build:

Build logs - the console output when your deployment is building which can be found under the Deployment Status section of the Project's Deployment page.

Troubleshoot Build failures

If your build fails, Lynfera will report the error message on the Deployments page so that you can investigate and fix the underlying issue.

Build logs - From your Lynfera dashboard, select the project then view the deployments tab or at the Deployments.
Select the deployment. When there are build issues you will notice an error status next to deployment name
On the errored deployment's page, you will see a summary of the error.

You can also view the logs from the build logs button from each deployment's or project's page.

It is recommended to build your project on your local machine first (the build command varies per project) before deploying on Lynfera. This will catch issues specific to your code or to your project's dependencies.

Build Logs not available

Builds can fail without providing any build logs when Lynfera detects a missing precondition that prevents a build from starting. Main reasons are:

It can be error on our own side.
Build process failed to start itself.
Network problems.
when using invalid Build Steps.
Logs got removed Learn more

Git Clone Errors

These errors can occur during a build when cloning repositories. The most common causes are:

Repository not found: This happens if the repository URL is incorrect, if the repository is private, or if its visibility changed. Verify the repository link and permissions.
Authentication failed: This occurs if you don’t have access to the repository or if the GitHub App installation is misconfigured. Try removing and re-adding the GitHub App.
Branch not found: The specified branch does not exist in the repository. Verify the branch name in the Project.Branch setting.
Other failures: These are usually caused by permission issues, token mismatches, or invalid repository URLs.

Troubleshooting Errors with Logs

View Logs details

Other Troubleshoots

Output Directory Mismatch

If your build "succeeds" but your site is blank or shows a 404, verify your Output Directory.

Vite: dist

React (CRA): build

Next (Static): out

Vue/Angular: dist

Routing & 404 Errors

In Single Page Applications (React, Vue, Vite), the browser handles routing. If a user refreshes myapp.com/dashboard, the server looks for a file that doesn't exist.

The Fix: Go to Project Settings and enable "Force non-file paths to root path". This tells Lynfera to serve your index.html for all virtual routes.

DNS / Hostname Resolution Errors

These errors are rare and usually occur when a specific subdomain cannot be resolved or is rejected by the hosting provider. Although they may appear as DNS failures in the browser, they are often caused by hostname routing, SSL, or connection issues rather than DNS itself.

You may see errors such as:

ERR_NAME_NOT_RESOLVED
ERR_CONNECTION_RESET
ERR_SSL_PROTOCOL_ERROR

These typically happen when a subdomain is temporarily unavailable, blocked, not yet propagated, or not recognized by the hosting platform.

Fix: Try changing your project subdomain or creating a new one. Using a slightly different name usually resolves the issue immediately. If the problem persists, wait a few minutes for DNS propagation and try again.