Diagnosing Stale Resources and Phantom Errors in Eclipse Incremental Builds

Recognizable Condition

The Problems view shows compilation errors on files that build cleanly from the command line (mvn compile or ./gradlew classes). After an external operation such as git checkout, npm install, or a code generator run, you may also see the marker Resource is out of sync with the file system.

Root Cause Taxonomy

Category	Typical Symptom	Underlying Mechanism
Workspace refresh disabled	Errors disappear after manual F5 refresh	Preferences → General → Workspace → Refresh using native hooks or polling unchecked
Incremental builder state corruption	Phantom errors persist across clean builds	Stale .markers or .syncinfo files in .metadata/.plugins/org.eclipse.core.resources/.projects/<proj>/
Linked resources / path variables	Project works for one user, fails for another	Path variables resolve differently after OS or user switch
Builder order conflict	Annotation‑processor generated sources not found	Java Builder runs before the code‑gen builder that creates generated-sources
Gradle/Maven nature mismatch	Buildship or m2eclipse reports missing plugins	Wrapper version out of sync with the IDE plug‑in (Buildship 3.x, m2eclipse 2.x)

Ordered Diagnostic Checks

1. Manual refresh – Select the project and press F5 (or File → Refresh). If errors vanish, the refresh policy is the culprit.
2. Clean without immediate rebuild – Project → Clean…, uncheck Start a build immediately, then toggle Build Automatically off and on. This forces a fresh incremental state.
3. Compare project metadata – Open .classpath and .project side‑by‑side with the VCS HEAD. Look for missing source folders, duplicate entries, or outdated classpathentry kinds.
4. Inspect the Error Log – Window → Show View → Error Log. Filter for Resource is out of sync or stack traces from org.eclipse.core.internal.resources.
5. External clean build – Run mvn clean compile or ./gradlew classes in a terminal (same workspace root). If the external build succeeds, the Eclipse model has drifted.

Fixes Mapped to Findings

Refresh Policy

• Enable native hooks: Preferences → General → Workspace → Refresh using native hooks or polling (check). On network‑mounted workspaces (NFS/SMB) prefer Polling with a 2–5 s interval to avoid high CPU.
• Alternatively, add a refresh goal to your Maven/Gradle launch configuration so the workspace refreshes automatically after each external build.

Builder State Corruption

• Close the affected project (Project → Close Project). Delete .metadata/.plugins/org.eclipse.core.resources/.projects/<proj>/.markers and .syncinfo. Reopen the project and let Eclipse rebuild.
• Risk: Deleting these files while the project is open can corrupt the workspace. Always close first.

Linked Resources / Path Variables

• Define shared path variables in Preferences → General → Workspace → Linked Resources (e.g., PROJECT_ROOT). Use ${project_loc} for project‑relative paths.

Builder Order

• Open Project → Properties → Builders. Move the code‑gen builder (e.g., Annotation Processing or a custom Ant/Maven builder) above the Java Builder so generated sources exist before compilation.

Nature Mismatch (Maven/Gradle)

• Maven: Right‑click project → Maven → Update Project…, check Force update of snapshots/releases.
• Gradle: Right‑click project → Gradle → Refresh Gradle Project, enable Force update of snapshots/releases.
• If Gradle daemon is stale (common with Buildship 3.x+), run ./gradlew --stop in a terminal before refreshing.
• Verify wrapper version: .mvn/wrapper/maven-wrapper.properties must specify Maven 3.8+ for m2eclipse 2.x.

Escalation Criteria

• Clean + refresh + builder reorder fails after two full cycles.
• Error Log shows recurring java.lang.IllegalStateException: Zip file closed or repeated Resource out of sync entries from org.eclipse.core.internal.resources.
• Multiple developers encounter the same issue after a shared .project/.classpath commit → file a bug against Buildship or m2eclipse, attaching the workspace .log (Help → About Eclipse IDE → Installation Details → Configuration).

Limitations & Practical Verification

These steps cover the most common drift scenarios for Eclipse 2023‑09 through 2024‑12 releases. They do not address:

• Custom builder plug‑ins that maintain their own state outside .markers.
• Workspace corruption caused by simultaneous Eclipse instances on the same metadata directory.

Verification checklist (run after each fix):

1. Create a minimal Java project with an annotation processor that writes to target/generated-sources/annotations.
2. Disable auto‑refresh, run mvn generate-sources externally, confirm the stale‑resource marker appears.
3. Toggle Refresh using native hooks or polling and verify that F5 behavior changes accordingly.
4. Inspect .markers before and after Project → Clean to confirm marker clearance.
5. After a git checkout that modifies .classpath, check the Error Log for org.eclipse.core.internal.resources entries.
6. Run ./gradlew --stop then Refresh Gradle Project to confirm daemon‑related stale state resolves.

If all checks pass, the workspace should stay in sync with the file system and external builds.