Here is a guide to getting your project back up and running the next time Eclipse bombards you with the R cannot be resolved error.

Every Android developer has run into this issue on more than one occasion: One minute everything is working fine, the next minute Eclipse is lit up like a Christmas tree. Nearly every module in your project fails to compile, and you're seeing red. Before you even look at the problem pane, you probably know that you are going to see "R cannot be resolved."

This is one of the most frustrating and common issues with the Android development platform. If you don't believe me, google the subject -- you'll find pages of developers asking for help and others offering to help solve this infuriating problem.

If there is already an abundance of suggestions and tips for resolving this issue, you might be wondering why I felt the need to write this article. Well, in my experience, there are numerous causes for this error, and sometimes it takes a minute to correct the error, and other times it takes hours to resolve it. Every time I comb the Internet posts, I read the same posts over and over and pick out one suggestion from myriad threads and sites. When everything is finally up and running again, I wonder why someone hasn't written a consolidated troubleshooting guide for this error. I decided to do it.

So without further ado, here is an exhaustive guide to getting your project back up and running the next time Eclipse bombards you with "R cannot be resolved" (Figure A). If you notice a scenario I missed, please let me know in the discussion thread. I will see that it is added to the troubleshooting guide, and that you get attribution for the tip.

Figure A (See an enlarged view of this image.)

1: Clean, clean, and clean

I know this sounds obvious, but you'd be surprised at how often this is the cure. In particular, if you recently refactored something like a package name, many times just a clean will get you back up and running. The suggestion that seems to work best in most cases is to turn off auto-build in Eclipse, do a clean of the entire project, and then re-enable auto build.

2: Disable Eclipse "auto imports" and "auto organize inputs on save"

Whenever your project has failed to generate the R file, turning Eclipse "auto imports" and "auto organize inputs on save" options off is a must (don't worry -- you don't have to leave these options permanently disabled). The reason is that once Eclipse can't resolve R it will sometimes add an "Import Android.R" to the top of your files that use resources. This is not what you want and, once it happens, you'll have to manually go through your source files, check for the bad import, and remove it by hand.

3: Check the /res directory for malformed XML

Eclipse is a big bulky environment, and sometimes it's slow to catch an error. There are many times I've created an XML resource, saved the file, and closed it without noticing any complaints from Eclipse. However, when the ADT finally does validate the XML, the generation of the resource file stops, and none of the source modules can locate the R file. As a matter of protocol, whenever I encounter this error, I open my entire resource tree in Eclipse and re-examine the folders / files for the red "X" indicating an error slipped by me.

4: Comply with Android file naming conventions

Android does not allow certain characters in file names that other development platforms do. Two that have stumped me on more than one occasion are the "dash" character and, wait for it, any uppercase character. File names for resources in an Android project may consist of lowercase letters, a period, and the underscore only. Any attempt otherwise will result in the platform failing to generate your resource package.

5: Double check your resource package name in the manifest

If you've gotten this far and still have not resolved the error, open your AndroidManifest.xml file and verify that you didn't inadvertently change your project's package name: <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="your.correct.package.name" ... .

6: Remove the "app_name" from the strings.xml file

While having an "app_name" in the strings file is not mandatory, the default manifest Android's project wizard creates a reference to it. My suggestion is do not remove the entry, but if you do, make sure to update the manifest to match.

7: Make sure you know your min and target SDK

Android is an evolving platform, and over time commands and keywords have been added. If you recently changed your target build, min SDK, or updated the tools, try rolling back to the previous SDK you were using by bringing up your project properties and selecting the previous SDK.

8: Are you using a version of the ADT greater than or equal to 22?

This only became an issue when Google rolled out its new Android Development Studio. Beginning with ADT 22, there is something called Android SDK Tools, and this package doesn't always seem to get installed as part of the auto update process.

To find out if you may be a victim of the persnickety installer, use the wizard in Eclipse to create a brand new "Hello World" application. If this project cannot generate R, there is definitely something askew with your environment. Open the SDK manager, find the tools folder, and make sure SDK Tools, SDK Platform Tools, and SDK Build Tools are all installed. If not, you can check the boxes, apply the install, and then restart Eclipse.

9: Create a new workspace

It may become easier to create a new workspace for your project than to continue to troubleshoot the existing one. I suggest trying to import your project; if that doesn't work, try creating a new project from the existing source. As a last resort, create an empty project and bring your application in piecemeal. This is time-consuming, but it should help to point you to the file or files causing the error.