Troubleshoot: Local
Local does a pretty good job of getting out or your way and letting you work with WordPress, but nothing works flawlessly all of the time!
Working through these common issues will:
- Fix things yourself so you can get back to work quickly!
- Have answers for when you ask for help!
note
For performance issues take a look at this help doc.
Table of Contents:
Where’s the Issue?
Good troubleshooting isn’t a skill only related to fixing things in Local. Being good at troubleshooting is about asking questions and zeroing in on what exactly isn’t working.
Whenever investigating something that isn’t working, get in the habit of asking yourself:
Where exactly is the issue?
What specifically isn’t working?
In the case of troubleshooting Local, some questions to ask:
- Is the Local App itself broken?
- Is there a problem with just one WordPress site, or all sites in Local?
- Is the issue Connect related, and the issue is with the remote site?
Issues with the Local App
Common problems with the Local app include:
- Error messages within the Local window
- Buttons within the Local window that do nothing
For many of these issues, the best place to start investigating is the Local log. This log is where Local records events of the various things that it encounters.
The easiest way to find the Local Log is by clicking “Reveal Local’s Log” from the “Help” menu. If for some reason you can’t access the menu, see this post in the Local Community Forums which goes into more detail.
Is the issue with all sites or only one in particular?
Identifying if the issue is happening on all WordPress sites or only one specific site, is a great way to narrow your search!
One easy thing to try is to create a new, plain WordPress site in Local. Does this new site have the same issue as other sites?
If you’re able to create and work with a new WordPress site, this tells you that Local appears to be working and it’s possible that the site with problems has become corrupted somehow.
When the problem affects all sites, inspecting the Local log is a good first step. In addition to the errors you find in the Local log, investigate the “Local Router Log” by clicking “Help > Reveal Local Router’s Log” from the menu.
You might be wondering what the “Local Router” is.
The Local Router is the nginx process which translates the human-readable domain into the specific port that the Local site is running on. For example, the Local Router would direct a request for example.local to the specific port that WordPress is listening on: localhost:10005.
If Local’s Router is causing issues, then one option is to try disabling the Local Router by setting “Router Mode” to localhost. More details about this setting can be found in this help doc.
Issues with one specific site
If you determine that only one site is having issues by successfully creating a new, plain WordPress site, a good next step is to try restoring the problem site to a new one in Local.
This can be done by either using a backup, or trying to use just the files for the site. More details about restoring a site from just the files can be found in this help doc.
If restoring a site to a new one in Local doesn’t work, then remember to keep asking yourself the troubleshooting questions from the beginning of this help doc:
Where is the issue? What isn’t working?
In the case of a single WordPress site, here are some things to consider:
Is the site actually broken?
One thing to note is that because Local is a development environment, there are settings in place that make errors seem more “noisy.” A site that seems to work on the remote environment might be showing what seem to be errors, but actually are just warnings. More information about this can be found in this help doc.
Try logging into the WordPress admin
Logging into the WordPress admin is a good way to see if the issue affects the whole site, or just the front-end. By default, logging into the WordPress admin is done by adding wp-admin to the end of the domain. For example, your browser should try to navigate to something like this:
http://example.local/wp-admin/
If you have issues logging into the admin, or the error still exists within the WordPress admin, there’s likely something wrong with the entire WordPress installation. A good place to continue to troubleshoot is reviewing the Debugging in WordPress documentation on WordPress.org.
In addition to the above WordPress documentation, common solutions might include:
- Disable all plugins and use the default theme. This might help zero in on third-party code that’s causing issues.
- Installing and using a plugin like Query Monitor to identify problem queries or issues with external requests.
Is only the WordPress front-end broken?
If the WordPress backend is working and you are able to log into the wp-admin, then there might be issues with some of the client-side functionality of the theme.
Changing to a different theme might help zero in on any issues. Alternatively, view the Browser Console to find any errors with the Javascript that’s being run.
The WordPress.org documentation on Using Your Browser to Diagnose JavaScript Errors is an excellent resource for debugging issues with client-side code.
Are there errors in the site’s server logs?
In addition to logging some errors within the Local Log, each WordPress site has logs for the various pieces of server software that are running the site.
When an issue is only happening on one specific site in Local, a good thing to check are the various error logs within the site’s logs folder. You can find this folder next to the app folder, wherever your sites are stored. By default, that location is within the ~/Local Site/sitename/logs folder.
Issues with Connect
Local Connect is a way to interact with a remote environment by either pulling changes down into Local, or pushing updates to the server.
A few things to keep in mind when troubleshooting Connect issues:
- What kinds of changes are you expecting to see? Caching might be an issue, so if you aren’t seeing changes after using Connect, try clearing the site’s cache.
- Sometimes there are problems with the remote server. Depending on where the site is hosted, log into either your Flywheel or WP Engine hosting account and reach out to their support!
Asking for help
If working through the above things doesn’t fix the problem, the next thing to do is search through these Local Help-docs to see if what you’re experiencing is documented.
Sometime the answer hasn’t been written about in our help docs, but someone in the the community has encountered the same issue and found a solutions. Try searching the forums and if nothing comes up, create a new topic with a good description of the problem, as well as outline the steps you’ve done in this help doc to get things working!
