SonarSource/sonarqube · error · IllegalStateException

Fail to traverse file:

Error message

Fail to traverse file: 

What it means

traverse() opens the previously written serialization cache file and returns a CloseableIterator over its objects. If the file cannot be opened for reading (IOException), e.g. it was deleted between write and read, it throws an IllegalStateException wrapping the cause.

Source

Thrown at server/sonar-ce-task-projectanalysis/src/main/java/org/sonar/ce/task/projectanalysis/util/cache/JavaSerializationDiskCache.java:80

    }
  }

  @Override
  public long fileSize() {
    return file.length();
  }

  @Override
  public CacheAppender<O> newAppender() {
    return new JavaSerializationCacheAppender();
  }

  @Override
  public CloseableIterator<O> traverse() {
    try {
      return new ObjectInputStreamIterator<>(FileUtils.openInputStream(file));
    } catch (IOException e) {
      throw new IllegalStateException("Fail to traverse file: " + file, e);
    }
  }

  public class JavaSerializationCacheAppender<O extends Serializable> implements CacheAppender<O> {
    private final ObjectOutputStream output;

    private JavaSerializationCacheAppender() {
      try {
        this.output = new ObjectOutputStream(new FileOutputStream(file, true)) {
          @Override
          protected void writeStreamHeader() {
            // do not write stream headers as it's already done in constructor of DiskCache
          }
        };
      } catch (IOException e) {
        throw new IllegalStateException("Fail to open file " + file, e);
      }
    }

View on GitHub (pinned to 184c821202)

Solutions

1. Ensure no external process (tmp cleaner, other worker) deletes files under the CE workspace while a task runs
2. Check that the cache file exists at the reported path and inspect filesystem health (NFS stale mounts)
3. Rerun the analysis task so the cache is rebuilt from scratch
4. Fix permissions so the sonarqube user can read its own workspace files

if (!file.isFile()) {
  throw new IllegalStateException("Cache file missing before traversal: " + file);
}
if (!file.canRead()) {
  throw new IllegalStateException("Cache file not readable: " + file);
}

try (CloseableIterator<O> it = cache.traverse()) {
  // consume
} catch (IllegalStateException e) {
  LOGGER.error("Cache traversal failed for {}", file, e.getCause());
  // rebuild cache by rerunning the producing step/task
  throw e;
}

When it happens

Trigger: traverse() called after the cache file was produced but FileUtils.openInputStream(file) fails — file removed by cleanup, workspace wiped between steps, or wrong file path/state.

Common situations: Concurrent CE workers or cleanup jobs deleting workspace cache files; NFS/network share with stale handles; cache file never fully written because an earlier step crashed.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Fail to write into file:
• Fail to open file
• Fail to write into file
• Ad-hoc rules export failed after processing %d rules success
• Can not write to file

AI-assisted analysis of SonarSource/sonarqube@184c821202 (2026-09-09). Data as JSON: /api/errors/944f1a5943f2d59e. Report an issue: GitHub.